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DYNAMIC VALUE MECHANISM FOR inheritance relationships. In an inheritance relationship, if a 

COMPUTER STORAGE CONTAINER routine to perfonn a certain type of manipulation is not 

MANAGER ENABLING ACCESS OF defined for a particular object in a particular class, then the 

OBJECTS BY MULTIPLE APPLICATION corresponding routine in the parent class is used instead 

PROGRAMS 3 whOe these languages can be used to address the i^ob- 

CROSS-REFERENCE TO RELATED ^"^^^^ ^^^'^l for handUng multiple content 

APPLICATION elements, it is not clear how that can be done. Certainly the 

languages themselves do not provide guidance on how they 

This is a continuation of U.S. patent application Ser. No. can be used for sudi purposes. For exaii^>le, the inheritance 

08/107,449, filed Aug. 16, 1993, now abandoned, which is mechanism in C-H- is a con^ile-tinie medianism. 

a continuation-in-part of U.S. patent appUcation Ser. No. The languages also permit a method for a given object 

08/060,809. entitled STORAGE EAGER FOR COM- (whether the method is defined specifically for the object's 

PUTER SYSTEM, inventOTs Shui Wing Lo, David J. Austin. own dass or is inherited from a superclass) to invoke other 

Tantck L Cclik. Steven J. Szymanski, and Janed M. Harris, methods for operating on the given object The method can 

filed May 12, 1993, which is incorporated herein by refer- ajg^ invoke whatever coOTsponding method is defined for 

ence in its entirety. the object's superclass, fOT operating on the given object 

BACKGROUND exactly which routine that might be. 

While these features permit some degree of hiding or 

Increasingly, documents and other collections of stored encapsulation, they do not provide enough flexibility for 

information are made up of multiple content elements, such easy development of application programs which manipu- 

as text tables^ images, formatting information, mathemati- late multiple content dements since to some degree, the 

cal equations and graphs. Often content is aeated using one application program still needs to know the type of the 

qiplication program and then included in documents aeated object it is operating on. 
by other applications. Subsequently, content elements may 

be copied out of a document and used in yet another ^ SUNIMARY OF THE INVENTION 

document and so on. According to tiie invention, rougWy described, a set of 

In the past, different applications typically had no way to procedures are defined which permit substantially arbitrary 

exchange multiple content elements, unless they had a composabllity of chains of handlers. The procedures follow 

**private contract" about the format to be used Furthennore, rules which render tiicm independent of the *type'* of tiie 

one application typically had no way to find the content value for which they are called, as viewed by the caller. Thus 

elements in another application's document, so typically it application programs can be written at only a high Icvd of 

was not able to obtain content elements from the other functionality, without needing to be concerned with the 

application's documents even if it knew the format. differences in the way different types of values need to be 

Moreover, every application developer who wanted to store ^5 handled. 

multiple content elements in a document typically had to The procedures determine which handler to call to per- 

develop a proprietary object storage mechanisia form a given operation in dependence upon the type of the 

The use of multiple content elements in a document object for which the procedure was invoked. The handlers, 

implicates at least two difficult issues: where each element too, are relatively easy to write because like the application 

is located and what the format of the data is. Regarding the 40 program, the rules permit the handlers to call the very same 

first of these issues, it would be desirable if tiie data in a set of procedures (recursively if the very same procedure is 

particular element could be stored in memory, in a local called) as are available to the application program. Thus like 

persistent stcrage device, across the network, or even ere- the plication program, handlers too can be written without 

ated dynamically, all in a manner which is transparent to the knowledge of any characteristics of the object for which 

^plication program whidi is operating on an element. In 45 they are invoked other than tiie characteristics defining the 

this way the limited resources available to application pro- type for which the handler is specifically written. For 

gram developers can be directed toward enhancement of example, a read handler for a type which defines a data 

functionality rather than dealing with multiple types of conqjression/decanp^ession algorithm need never know 

storage devices. where the data is physically located since it merely calls the 

Similariy, with regard to the second issue, it would be 50 Predefined read value procedure to obtain the data to decom- 

desirable if each different content element could have stored press. 

inassociation with it aU of the routines whidi are needed to Types can be defined in a tree structure. This further 

manipulate it, again, transparentiy to the application pro- simplifies the writing of handlers since the different diar- 

graxa This, too, would free up developers' resources for acteristics of a type can be divided into many small 

more useful purposes. 53 con^wnents, eadi defined by a different sub-type on the tree. 

In a general way, an individual devdoper migjit obtain Thus each handler can t>e written to accomplish only a 

some of the Iransparcncy described above by programming limited objective (for example an I/O redirection or a data 

the application using an object-oriented programming Ian- transformation). The predefined procedures automatically 

guage such as C++. Object-oriented programming is follow flie diain of handlers defined by a type tree, by 

described in many references, induding, for example, G. 60 knowing where in the chain a given caller of the procedure 

Booch, "Object-Oriented Design With Applications" is. Ndtha the application program nor the handlers them- 

(Benjamin/Cummings Publishing Company: 1991). incor- selves need keep track of this information, 

porated herein by reference. Sudi languages often support Additionally, the predefined procedures make no assump- 

the grouping together of both an item of data and a set of tions about the types in a type tree. An application developer 

••metiiods" to manipulate the data, in a single "object". These 65 can define novel types as required by dividing them into 

languages also often indude, through a mechanism known subtypes (if desired) and writing handlers for each subtype, 

as "classing" and "sub-classing" of objects, a way to define As mentioned, the complexity of tiie handlers depend only 
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on the cQnq)lexity of the transfonnation or redirection which 
they are to individually perfonn. not on the compl^ty of 
either the type tree or the procedures which implement the 
present invention. So long as the handlers foUow certain 
rules of good behavior, the predefined procedures will be 
able to follow any such user-defined type tree. Additional 
procedures are provided for assodatiDg the individual han- 
dlers to their corresponding types (subtypes), and for build- 
ing the type trees themselves. 

To implement the above procedures, computer apparatus 
stores a subject value and a chain of sequentially associated 
value handlers for the subject value. Tbe chain includes a top 
value handler and a bottom value handler, each of the value 
handlers in the chain except the bottom value handla 
invoking the respective next value handler when invoked, 
die bottom value handler performing an operation on the 
subject value when invoked. Hie value operations can be 
data read operations, data write operations, etc., and the 
value handlers in the chain can perform data transformations 
and/or data redirections, transparently to its callei. 

The dynamic value chain is not stored in persistent 
storage; rather it is created when an appUcatioa program 
desires to peifoim a value operation on the subject value. 
The subject value has a t^ associated with it which 
determines the value handlers to be placed in the chain. Hie 
diain can have more than one value handler in it for a given 
value operation if the type associated with the subject value 
is made up of a hierarchy of sub-types. 

BRIEF DESCRIPTION OF THE DRAWINGS 

The invention will be described with respect to particular 
embodiments thereof, and reference will be made to the 
drawings, in which: 

FIGS. 1 and 2 illustrate type trees; 

FIG. 3 is a block diagram of a hardware computer system 
platform whidi the invention might be used; 

FIG. 4 is an overall block diagram of major data structures 
which are created in main memory of the computer system 
of FIG. 3 during the pendency of a session; 

FIG. 5 illustrates the structure of in-memory objects 
which are created by dynamic value mechanism according 
to an embodiment of the invention; 

FIG. 6 illustrates the same structure as FIG. 5 using a 
simplified notation; 

FIG. 7 illustrates a type object using the notation of FIG. 
6; and 

FIG. 8 is a flowchart of a CMRcadValueDataO routine 
used in an embodiment of the invention. 

DETAILED DESCRIPTION 

The embodiment described herein takes the form of a 
Container Manager and its associated data structures which 
can be used by developers of a wide variety of types of 
application programs. The Container Manager includes a 
number of C language type definitions and a number of 
procedures for implementing the functionality provided by 
the Container Manager. Together they provide a common 
^plication program interface (API) for the different types of 
application programs. 

The stnidures are described first with respect to their 
logical organization and subsequently their physical orga- 
nization in the storage apparatus managed by the container 
manager. That is, they will be described first with respect to 
the view which the container manager software provides to 
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an application programmer via the API, and subsequently 
with respect to the way that logical organization is actually 
implemented in the present embodiment While many of the 
advantages of the present invention derive from the logical 

5 organization, it will be apparent that such logical organiza- 
tion implies certain physical structures whidi arc required to 
maintain the metaphor as viewed by the application devel- 
oper. The physical organization described hereinafter 
includes many inventive aspects of the invention, but it is by 

10 no means the only physical structure which can support the 
logical organization presented to the ^plication developer. 

TABLE OF CONTENTS 

I GENERAL OVERVIEW 

A. Overview of Container Manager Entities 

B. Overview of lypcs and Dynamic Values 
C Format Overview 

D. Format Definition 
^ XL XMPLEMENTAnON 

A. Hardware 

B. In-Memoiy Data Structures 
C Routines 

2j 1. Session Operations 

2. Object Opemtions 

3. TVpe and Property ()perations 

4. Value Operations 

nL DYNAMIC VALUE HANDLERS 
30 A. Sample Session Flow 
B. San^le Value Handlers 

APPENDIX A 

APPENDIX B 

APPENDIX C 
35 APPENDIX D 

L GENERAL OVERVIEW 

In the present embodiment, an object is a collection of 

^ data that 'liangs together" and that can be referenced by 
other data. Objects can be single or coiiq)lex, small (a few 
bytes) or large (up to 2^ bytes). Compared with objects in 
languages such as C-H-, objects of the Container Manager 
are typically larger and more complex, because they repre- 
sent user meaningful content elexx^nts, rather than the atoms 
and molecules used to build this content. 

For example, a sequence of bytes of data would not by 
itself be an object, because we can only undentand the bytes 
if wc know how they will be used. A paragraph, an image, 

50 etc. can be an object if it contains enough information so that 
we know how to interpret it T^ically an object contains 
information about what kind of object it is, and some data, 
which provides the content of the object. In this description, 
the information "about** the object is called metadata, and 

55 the content of the object is called its value. 

The Container Manager groups objects in an object 
container, which is some form of data storage or transmis- 
sion (such as a file, a piece of RAM, or an inter-application 
message) fiiat is used to hold one or more objects (both their 

60 metadata and their values). These containers are defined by 
a set of rules for storing multiple objects in a such a 
container, so that software that understands the rules can find 
the objects, figure out what kind of objects they are, and use 
them corrcctiy. The rules accommodate a wide variety of 

65 different kinds of objects, different ways that ^plications 
want to use objects, and system considerations about how 
data can be stored. 
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The Container Manager provides a container definition be 21 bytes. For a small value whidi is one of several values 

that can conveniently, efficiently, and reliably hold all the associated with a property, the overhead can be as low as five 

different lands of objects that users and applications want to bytes. 

group together, store, and exdiange. The Container Manager IVpes. The type of a value describes the format of that 

docs not define how any given object is structured internally 5 value. Types record the structure of a value, whether it is 

(within its value) so as not to limit the fonnats which an compressed, what its byte ordering is, and so on. The 

application developer may want to define. Objects stored in Container Manager provides an open-ended mechanism, so 

a contamer can have proprietary or standard fonnats, they that t>pcs can be extended to include whatever metadata is 

can be designed to use &e Container Manager mechanisms required. 

cr they can be completely ignorant of the existence of the lO To continue the exanqilc above, the type of a string value 

Container Manager. could indicate the alphabet, whether it was null terminated, 

A. Overview of Container Manager Entities and possibly other information (such as the intended 

The Container Manager manipulates and stores data using language). It might also indicate that the string was stored in 

primary and secondary entities. The primary entities used by a compressed form, and could indicate the compression 

the Container Manager are containers, objects, properties, 15 teclmique, and the dictionary if one was required. If the 

values, and types. string used multi-byte characters, and the byte-ordering was 

Containers. Every object is in some container. An object not defined by the alphabet, the type could indicate the 

consists of a set of properties. The proporties arc not in any byte-ordering within the characters, 

particular order. Each property consists of a set of values The Container Manage defines an inheritance mccha- 

with distinct types. The values are not in any particular 20 nism to make building complex types like this efficient The 

OTder. Every object must have at least one property, and that structure of types is tied into the mechanism for accessing 

property must have at least one value. Each value consists of values, so that the type associated with a value causes the 

a variable length sequence of bytes. appropriate code to be invoked to access the value, decom- 

The Container Manager knows very litde about a con- press it, byte-swap it, and so on. The specific medjanism for 

tainer beyond the objects in it. However, the container 23 doing this is refcrrcd to herein as Dynamic Values, 

always contains a distinguished object, and ^plications can Secondary Entities. In addition to the primary entities 

add arbitrary properties to that object, so plications can manipulated by the Container Manager, there are several 

specify ftirther information about the container if they wish. additional entities that play suppating roles in the Container 

Containers are often files, but they can also be many other Manager design. These entities are inq)ortant to fully under- 

forms of storage. For example, in various applications 30 stand how The Container Manager works, but they do not 

developers ahready support the following types of contain- significantly change the picture given above, 

crs: blocks of memoty, the clipboard, network messages, and Type and property descriptions. Each property associated 

Container Manager values. Undoubtedly other types of with a value is actually a reference to a property description, 

containers will be useful as well. Similarly, the type of a value is actually a reference to a type 

Objects. Eadi Container Manager object has a persistent 35 description. These type and property descriptions are" 

ID which is unique within its container. Other than that, objects, and their IDs are drawn from the same name-space 

objects don't really exist independent of their properties . An as other object IDs. 

object contains no information beyond what is stored in its Many type and property descriptions will singly consist 

properties. of the globally unique name of the type or property. To 

Properties. A property defines a role for a value. Proper- 40 continue the example above further, the type of a string of 

ties are like field names in a record or struct, with two 7-bit ASCH, not compressed or otherwise transfonned, 

differences. First, properties can be added freely to an object, would simply be described by a globally unique name. This 

so an application should never assume an object only has the would allow applications to recognize the type, 

properties it knows about Second, property names arc References to type and property descriptions are distinct 

globally unique, so that they can never collide when various 45 from references to ordinary objects in ttie API to allow 

different applications add properties to the same object This language type checking to catch errors in the manipulation 

also means that the same property name ahvays means the of type and property references. However, type and property 

saine thing, no matter what object it is in. Properties arc references can still be passed to the Container Manager 

distinct from types, just as field names are distinct from the routines which manipulate user-defined objects and vahjes, 

data type of the field. so so that value manipulation can be done on types and 

For example, different properties of an object might properties in the same manner as it can be done on usct- 

indicate the name of an object, the author of the object, a defined objects. 

comment a copyright notice, and so on. Hiese different Globally unique names. Globally unique names are public 

properties could all have values of the same type: string. or private identifiers in a format defined by the ISO 9070 

Conversely, a property indicating the date created might 35 Public Text Identifier standard. They are simply strings 

have a string, Julian day, or OSI standard date rep-esenta- written in a subset of 7 bit ASCIL They begin with a name 

tion. These different formats would not be indicated by the that is assigned by a naming au&ority designated by ISO 

iwopcrty, but by the type (see below). (companies can easily register as naming authorities). After 

Values. Values are where the data is actually stored. In this come additional segments, as determined by the naming 

terms ofj^ysical location, this data might actually be stored 60 authority, each of which is unique in the context of the 

anywhere in a container. In fact, it can be broken up into any previous segments. 

number of separate pieces, and ttie pieces can be stored The most common globally unique names will be gener- 

anywhere. (See the discussion of value segments below.) ated by system vendors or commercial application 

Each value may range in size from 0 bytes to 2^ bytes. developers, and may be registered. However, in many cases 

although that range can differ in a different embodiment Hie 65 names will be generated by vertical application developers 

overhead per value varies depending on the circumstances. to recOTd their local types and properties. To meet tiiis need. 

For an object witii a single value, the typical overhead will the naming rules allow for local creation of unregistered 
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unique names, far example by using a product serial number 
as one of the name segments. 

IDs. The Container Manager assigns each object a per- 
sistent ID that is unique within the container in which the 
object is created. These IDs are never reused once they have 
been assigned, so even if an object is deleted, its ID will 
never be reassigned. 

These IDs are obviously essential to the functioning of the 
Container Manager format* but they do not ^pear directly 
in the APL The only points at whidi an ^plication actually 
deals with anything corresponding to an H) is when it needs 
to store an object reference into a value, or find (he object 
coircsponding to a reference retrieved from a value. Even in 
this case, however, the AFI does not give die application 
direct access to an object ID, but only to a token that 
corresponds to the ID in the context of that particular value. 
This hiding cf actual IDs permits the Container Manager to 
pcifoim reference tracking. 

Refiiums. In the API, types, properties, and objects are 
refeired to using opaque reference numbers provided by the 
Container Manager. The refnums are much more convenient 
to use than IDs because they are unique within the session, 
while an ID would need to be used together with a container 
reference. Since they are opaque, they allow in^^lementa- 
tions of the API that support caching schemes in whidi only 
pcMtions of the container metadata are in memory at any 
given time, 

Refriums have no persistent meaning, so they cannot be 
stored in values as references to other values. The tokens 
provided by the reference calls must always be used for 
persistent references. 

Dynamic values. As mentioned above in the discussion on 
*Types*', a Container Manager value can be compressed, 
encrypted, byte-swapped, etc. during read/write. 
Furthermore, these transformations can be composed 
together to form a chain of transformations. 

Li addition to data transformation, the same mechanism 
also supports I/O redirection. In this case a value actually 
stored in a container is a description of how to find the data, 
rather than the data itself. Such descriptions can be as simple 
as references to files, or to objects in another container, or as 
complex as queries that cause data to be retrieved from a 
database. 

Both I/O transformations and I/O redirection are carried 
out implicitly by the Container Manager library, using 
*Tiandlers" determined by the type of the value. These 
handlers are attached to tenq)orary entitles called dynamic 
values created by the library. Dynamic values arc never 
visible to the application, and have no persistent meaning. 
Hie Dynamic Value mechanism is described in more detail 
below. 

Value segments. To support interleaving and other uses 
that require breaking a value up into pieces. The Container 
Manager allows a value to be stcffed as multiple segments 
stored at difFerent locations in the container. These segments 
are not visible at the API, since the Container Manager 
routines concatenate them to create a single stream of bytes. 

The Container Manager also takes advantage of value 
segments to rqpxcsent insertions, deletions, and overwrites 
of contiguous bytes in a value. This allows the Container 
Manager to represent these operations directly in recording 
updates, rather than having to create a new copy of the value. 

Handlers. The Container Manager makes use of dynami- 
cally linked handlers supplied by the execution environment 
for two reasons: portability and extensibility. The use of 
handlers means that the Container Manager library is almost 
trivially portable, since all the system dependencies arc in 
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the handlers. The Container Manager library is also easily 
extensible, with the addition of newty written handlers, since 
the handler interfaces are carefully designed to provide 
cleanly encapsulated abstractions. 
5 The Container Manager employs session handlers, con- 
tainer handlers and value handlers. Session handlers are 
global to the session as a whole. These indude allocating 
and de-allocating memory, and reporting errors. Container 
handlers perform all of the actual 1/0 to containers. These 
handlers map I/O to the underlying storage in a way that 
depends on the container type. Container handlers basically 
provide a stream 1/0 interface to the container storage. 

Value handlers implement both 1/0 transformations and 
value indirection. These handlers are determined by the type 
of each value. New handlers to carry out new types of data 
transformations or support new types of indirect values can 
be written at any time. 

These handlers arc invoked entirely by the library. The 
accessing application does not need to know that it is using 
handlers to access the value. Of the three kinds of handlers 
20 used by the Container Manager, only the value handlers are 
described in detail hacin since they arc the only ones which 
are important to an understanding of the invention. 
B. Overview of TVpes and Dynamic Values 

The Container Manager provides a very powerful mecha- 
25 nism for transforming values during I/O, and for foUowing 
indirect references. The Container Manager type mecha- 
nisms are probably best explained in terms of some usage 
examples. 

Usage example 1 — External Hie. Suppose an application 
30 developer would like to have a value that represents a file. 
When the application calls the Container Manager's Write 
Value Data procedure (CMWriteValueData) for writing data 
to the value, we want to actually perform 1/0 to the file. 
The mechanisms described herein aUow us to store a 
35 reference to the file in a value. When the value is used, an 
I/O redirection is set up, without the application being aware 
of it. 

Note that this raises the thorny problem of platform- 
independent file references. The Container Manager avoids 

40 this problem. It allows any number of different types of 
references, in^lemented by handlers. 

Usage Exanq)lc 2 — Conqiressed Value. Suppose an appli- 
cation developer would like to compress data as it is written 
to the value, and deconqircss it as it is read out. In addition 

45 to maintaining the data in the value itself, this coiiq)ression 
may depend on a dictionary associated with the type of 
value. Furthermore, the compression routine may need to 
maintain a state, since the con^iression at any point may 
depend on what has already been written. 

50 The mechanisms described herein allow us to give the 
value a type that causes the con:^>rcssion/dccoiiq)rcssion 
handler to be transparently invoked when the application 
does I/O. Again, this is an extensible medianism, so that 
new coriq>ression algorithms (or more generally, arbitrary 

55 transformations) can be added without modifying the 
library. 

Usage Example 3 — Coir^ressed, Format Converted 
Array. Si^>pose the value which an application is dealing 
with is actually an array of pixels. In addition to decom- 

60 pressing it, on a given platform we want to convert each 
pixel to a different format 

The mechanisms described herein allow us to take two (or 
more) data transformations, such as compression and format 
conversion, and compose them together. Just as the appli- 

65 cation does not need to be aware of the underlying 
transformations, the individual transfoimatioiis do not need 
to be aware of each other. 
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Usage ExaiBple 4 — ^All of the Above. The next step is to 
put the compressed pixel airay out in a file, and conveit it to 
a different foimat when it is read in. This is all supported 
using exactly the same composition as used in the previous 
exan:i|)le. The interfaces to data transformations and I/O 5 
redirection arc the same, so no special mechanism is 
required. 

Oflicr Usage Examples. To briefly illustrate further where 
this leads, here are some further examples: 

A value contains a query that is used to look information iq 
up in a database. The "I/O redirection" provides access 
to a table retrieved from the database. 

A value contains a file reference that is encrypted because 
it also holds the file-server password. A decryption 
stage is required before the I/O redirector can be 13 
applied to the file reference. 

A value contains a query that is used to generate a file 
reference, which dien becomes the basis for a second 
level of I/O redirection. 

Numerous other usages can be developed whidi can take 20 
advantage of the mechanisms described herein. 

All of the above examples are based on the types asso- 
ciated with the values involved. The examples depend on 
two aspects of Container Manager types. 

First, every value handler is bound to values only indi- 25 
rectly throu^ the name of a type. Handlers are associated 
with type names through the C>fSctMetaHandler Container 
Manager operation. This association is session-wide. Then 
the handler is bound to a particular type in a given container 
through the name of that type. This binding is done when the 30 
container is opened. 

Second, even in &e simplest exan^les above, such as the 
value that is merely an indirection to a file, or the value that 
is merely conqx^essed, the value essentially has two types: 
the type visible to the application, which encodes the format 35 
of the data from the application's point of view, and the type 
used to find the appropriate handler for compression, I/O 
redirection, etc. 

As the more complex examples show, multiple types of a 
value need to be independent. This leads to a view of a value 40 
as having multiple, independent types. By analogy with C++ 
(an analogy M^ch is not perfect, as described below) we call 
tiiesc "base types** of the value's type. Base types can be 
added to and removed from any Container Manager type 
using the Container Manager CMAddBaselVpcO ^ 
CMRemovcBaseiypeO operations. 

Base types are ncxmal types, and themselves may have 
base types. This could be useful, for example, when the 
combination of file access and deconopression is used in a 
variety of different contexts. The two could be made base 30 
types of a new type, and then that new type could be used 
in various ways, including making it a base type of the '*all 
of the above** type whidi adds foimat conversion. 

To illustrate the concept of base types, FIG. 1 is a 
symbolic diagram of a tree having three types 102, 104 and 55 
106. A value may have a "compressed file type** 102 
associated with it, but the comparessed file type 102 has two 
base types: a **file access type** 104 and a "compression 
type" 106. The complex "compressed file type" 102 can be 
created by first defining the compressed file type 102 object, 60 
than calling the Container Manager procedure to add a base 
type 104 to the type 102, and then by calling the procedure 
again to add the base type 106 to the compressed file type 
102. 

FIG. 2 illustrates a more complex type tree. As shown in 65 
FIG. 2, the type **format converted compressed file type** 
202 has two base types, "conprcssed file type*' 204 and 



879 

10 

**fonnat conversion type'* 206. As with compressed file type 
102 in FIG. 1, compressed fiile type 204 has two base types, 
•*file access type" 208 and "conpression" 210. 

The addition of base types will always form a tree routed 
in the original type. If the same type is used as a base type 
in more than one place in the tree, the separate uses are 
treated as entirely separate types. 

To understand how a given tree of types will behave, the 
tree is flattened into a linear "chain'* of types. In the present 
embodiment, this is done by performing a depth-first post- 
order walk on the tree. Thus, in the case of FIG. 1, the 
resulting sequence is file access, compression, then com- 
pressed file. If an application program calls the Containa 
Manager routine to read data from a value 
(CMReadValucData), and the value has the type, "com- 
pressed file", then the Container Manage will first call the 
read handler for the compressed file type 102. The read 
handler for the compressed file type 102 will then (through 
another call to CMReadValueData) call the read handler for 
the compression type 106, which in turn calls (through yet 
another call to CMReadValueData) the read handler for file 
access type 104. The read handler for file access type 104 
obtains (through yet another call to CMReadValueData) the 
information which is stored in the container in the storage 
area allocated to the value which the application desires to 
read, and uses this information to access the actual data on, 
for exanqile, a hard disk. This data, obtained from the hard 
disk, is the return value of the read handler for file access 
type 104. This data gets decompressed by the read handler 
for compression type 106, and then returned to the caller by 
the read handler for the conqiressed file type 102. 

The chain formed by the flattened type tree is considered 
herein to have a 'top*' and a "bottom" type whidi are, 
respectively in FIG. 1, conqscssed file type 102 and iilc 
access type 104. This means that flie first handler to be called 
for any value operation is the value handler associated with 
the *top" type on the chain. That handier invokes the next 
handler on the chain, which in turn invokes the next handla 
on the chain, and so on down to the ''bottom" handler on the 
chain. The handlers tiien return one by one to their respective 
calling handlers, until the "top" handler returns to the 
application program. 

In the type tree of FIG. 2, the depth-first, post-order walk 
of the tree flattens it into the following linear chain: file 
access type 208, compression type 210, con^>ressed file type 
204, format conversion type 206. and format converted 
compressed file type 202. Format converted compressed file 
type 202 is the *tap" type on the chain, and '"file access" type 
206 is the *1x)ttom" type on the chain. Note that confessed 
file type 204 and format converted compressed file type 202 
do not have handlers associated with them (let us assume), 
they will not have any effect on the value. 

In order to support the above exan^les, the present 
embodiment assumes two design constraints. First, the 
application, and each handler, must always think that it is 
dealing with a *'nonnal" value (i.e. one without redirection 
or transfonnations); that is, any redirection or transforma- 
tion must be completely transparent to the caller. Second, in 
several cases we saw that handlers might have a non-trivial 
amount of state to manage. 

We address these constraints by giving eadi handler its 
own **privatc" value, called a dynamic value. Dynamic 
values are transient (i.e. not persistent); they are created just 
to provide an environment for the handlers, and they are 
never written to the container, saved in the container's Table 
Of Contents (TOC), etc. However, they do haverefnums and 
from the "outside" (i.e. from any application code or handler 
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code except the handler that "owns" them) they look exactly 
like nomial values. It will be seen that dynamic values have 
the same *Value header^ as real values, except that instead 
of pointing to storage locations which contain actual value 
data, they point to a vector of *1jandlers", one for each of a 
predefined set of **valuc operations", to be called when a 
prior caller desires to use the value. 

The following value operations arc supported by the 
Container Manager. The Container Manager routines which 
implement these operations first check whether the specified 
value is real or dynamic. If real, then the routine simply 
operates on the real data. If dynamic, then the routine calls 
the handler which is associated with the specified value for 
the specified value operation. Thus for a given dynamic 
value, a handler can be provided to support each of the 
following value operations: 



® 1992 Apple Computer, loc 

CMSize CMGet\yueSize(CKfVahu vahie); 

CMSize CMReacI\%hidOata(CMVahic value, CMPtr buffer, 

CMOount offset, C!MSize xoaxSize); 
void CMWciteYahieData(CMN^lae value, CMPtr buffer, 

CMCouot offset, CMSize size); 
void CMlDsert\^daeData(CM'^ahiB value, CMPtr buffer, 

CMCouat offset, CMSize size); 
void CMDeleteValueData(CMWlue value, CMCcunt offset, 

CMSize size); 

void CMGetVahieInfo(CMVaIue value, CMContaiDcr *coiilaiiier, 
CMObjcct ^object, CMPropcrty •property, 
CMiype 'type, CMGeneration *genention); 

void CMSetWueiyFe(CM\^Uue value, CMiype type); 

void CMSetVilueGeaexatiou(CMVah£ valos, 
CMGeueratiQa genentbu); 

void CMRe]ea£eValue(CMValue); 



As an aside, the present description often uses C-language 
notation as a shorthand way of describing the steps per- 
formed by, or other characteristics of, a Container Manager 
routine. In this notation, all module names and external data 
diat can possibly be visible to an application programmer 
begin with the letters "CM** or "cm". The upper case **CNr' 
prefixes all API visible routines and macros. The prefix 
••kCM" is used for constants. The lower case "cm" is used 
for all inter-module references within the Container Man- 
ager. All other data and modules have no other naming 
conventions and should not be visible outside of the file in 
whidi they occur. Macros used within the Container Man- 
ager do not follow these conventions since they are never 
visible in the generated object modules. Thus names begin- 
ning with "cm" or (upper or lower case) are reserved by the 
API and should not be used by the ^plications using the 
AH. 

Also as an aside, routines or code portions which are not 
described herein are considered sdf-documcnting cither due 
to commenting or due to the use of self-documenting symbol 
names. For example, it will be parent to the reader without 
further explanations that the CMGetValueSize() operation 
mentioned above returns the size of the specified value. 

Returning again to the above Container Manago* value 
routines, none can be called for a particular value until one 
of the foEowing inreparatoiy routines are called for that 
value: CMNewValueQ or CMUseValueQ. As described 
below, if the desired value is a dynamic value, these routines 
set up the chains of dynamic value handlers needed to 
support the above routines. 

When a dynamic value is spawned by CMNewValue() or 
CMUseValue(), the pointer to the top-most dynamic value 
header is returned as the refNum. Then, whenever tiie user 
passes a refnum to an API value routine, it checks to see if 
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the rcfNum is a dynamic value. Jf it is, it initiates the call to 
the coiiesponding value handler. That may cause a search up 
the base value diahi to look for an 'Inherited" value routine. 
Id the limit, we end tip using the original API value routine 
if no handler is supplied and we readi the '"real" value in the 
chain. Thus the handler must be semantically identical to the 
corresponding API call. 

These dynamic values only exist from crcatioo during the 
CMUseValueO until they are released by CMReleaseValue 
' (). A dynamic value can have its own data, but this data is 
stored in the value's lefCon ra&cr than in the value data 
itself. Dynamic values do not have associated data in the 
normal sense. 

; A dynamic value is created wlien a value is created by 
CMNewValueQ or used by CMUseValueQ, and the follow- 
ing two conditions occur: 

1. The type of the value, or any of its base types, have 
metahandlers which have been registered by the Container 

20 Manager CMSetMetaHandlerQ routine in a session-wide 
metahandlex symbol table (CMSetMetaHandlerQ is usually 
called when a container is fiirst opened); and 

2. The metahandlers support a Use Value Handler, and in 
addition for CMNewValueQ, a New Value Handler. 

25 The New Value Handlers are used to save initialization 
data for the Use Value Handlers. The Use Value Handlers are 
called to set up and return a refCon. Another metahandlo: 
address is also retursed. This is used to get the address of the 
value operation handlers corresponding to the standard API 

^° CM . . . value routines mentioned above. 

When a CMNewValueQ or CMUseValueQ is almost 
done, a check is made on the value's type, and all of its base 
types (if any) to see if it has an associated regista-ed 

3 j metahandler. If it does it is called with a Use value operation 
type to sec if a Use Value Handler exists for the type. If it 
does, we spawn the dynamic value. 

The spawning is done by calling &e Use Value Handler. 
The Use Value Handler is expected to set up a ref Coo to pass 

40 among the value handlers and a pointer to another metah- 
andler. These are returned to CMNewValueQ or 
CMUseValueQ which does the actual creation of the 
dynamic value. The extensions are initialized, the metahan- 
dler pointer and refCon are saved. Hie pointer to the created 

45 dynamic value header is what CMNewValueQ or 
CMUseValueQ returns to the user as the refNum. 

Now, when the user atten^)ts to do a value operation using 
this refNum, we will use the corresponding handler routine 
in its place. The vector entries are set on first use of a value 

50 opsation. If a handler for a particular operation is not 
defined for a value, its **base value" is used to get the 
•^inherited" handler. This continues up the chain of base 
values, up to the original **real" value that spawned the base 
values from the CMNewValueQ or CMUseValueQ. Once 

55 found, we save the handler in die top layer vector (associated 
with the refNum) so we don't have to do the seardi again. 
Thus, as in C++, dynamic values may be "subclassed" via 
their (base) types. 
Note that if we indeed do have to search up the base value 

60 chain then we must save the dynamic value refNum 
(pointer) along with the handler address. This is very much 
like C++ classes, where inh^ited methods are called and the 
appropriate '*this" must also be passed. 
The Container Manager supports layering of dynamic 

65 values. The best way to describe layering is in terms of C++. 
Say we have die following dass types (using a somc\\iiat 
abbreviated notation): 
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dass. In the Container Manager, all "classes** (i.e., our type 
— — — — — — — — objects) are created dynamically. So the problem is we need 

o 1992 Apple Coiiq>utei, Inc. somc Way to tcll What data "belongs" to what type. 

class Layer { //a baa class Solution is yet another special handler, which returns 

<iaycri data> // possible data (adds) 5 » format Specification called metadata. The handler is the 

La7eri(<iayeri az^); // coostiuctar to init the data Metadata Handler whose address is determined by the 

other methods^. // vahie operations in our case Container Manager from the Same metahandler that returns 

the New Value and Use Value Handler addresses. 

''^^'^^ (^«.) , ^ very siinto to C-language print^) format 

U?cr2(<layer2aigs>); // asistnictar to init ic cfata lo ^cscnptions^ and IS uscd for Similar puiposcs. The next 

other methods... // vahie operations in our case section will describe tiie metadata in detail For now, it is 

class T:LayerULa3rer2{ // tiv class of inteicstl sufficient tO knOW that it tcUs CMNewValueQ hoW tO 

<l data> // possible data (fields) interpret its . . " parameters. The rest of this section will 

T(<T argsxiaycri args>. <iayert arK!£>); dig^uss how this is done to dynamically create data. 

// canstnictor to mt the data aul bases . „ „ m i ^^ *v j I • * j j. i 

othermethods... // vahie operations in our case As With C++ dasses, the data IS created When a Dcw valuc 

}; 1^ is created, i.e., with a CMNewValueQ calLTlic data will be 

' saved in the container, so CMUseValue() uses the type 

, ^ . , , format descriptions to extract the data for each dynamic 

In CoQtamer Manager terminology, T is to be a registered ygi^e layer, 

type with other registered types as base types (classes). All CMNewValueQ is defined witii the following prototype: 

type objects are created using the standard AH call 20 

CMRegisterT^eQ. Base types can be added to a type by — 

using CMAddBaseTypeQ. This defines a form of inheritance CMVah» CMNewVahje(CMObject object, CMPjopcrty property, 

like the C++ classes. canype type, -.); 

Type T would be registered with its base types as follows: ' 



O 1992 Apple Computer, Inc. 



25 The **...*' is an arbitrary number of parameters uscd to 
create the data. Metadata, accessed from the Metadata 
Handler, tells CMNewValueQ how to interpret the param- 
layeri = CMRegistcrType(containcr, "Layeri"): ctcTS just like a printfQ format tells printfQ how to use its 

layer2 = CMRegisteiType(contaiDer, Xayer2**); arguments, 

J^^^^iS^l"""^* Qf^Q. of tjjg parameters is important Because base 

SIl^I^^^ uy^, ^« ^o^^ a depth-first seardi through the types 

down to their leaves, the CMNewValueQ . . ** parameters 

must be ordered with the parameters for the first type in the 

For the t object, the global name property and value are chain occurring first in the parameter list Note what's 
created as usual by CNDlcgistctTVpc (container, *T"). The happening here is that the user is supplying all the construc- 
CMAddBaseiype Q calls add the base types. These are tor data just like T constructor class example above, 
recorded as the object ID*s for each base type in the order The way the data gets written is with a special handler, 
created as separate value segments for a special "base type" called the New Value Handler. After CN/NewValueQ calls 
property belonging to the type object the Metadata Handler, it uses the metadata to extract the next 

As mentioned above, OvDiewValueQ or CMUseValueQ set of CMNewValueQ **..." parameters. CMNewValueQ 
spawn dynamic values if the original type or any of its base 40 then passes the parameters along in the form of a data packet 
types have an associated Use Value Handler. Assume that to the New Value Handler: The New Value Handler is then 
was done for *T' in the above exan4>le. What happens is that expected to use this data, which it can extract with flic 
CMNewValueQ or CMUscValue() will look at its type Container Manager CMScanDataPacketQ routine. Once it 
object (t here) to see if the base type property is present If has the data, it can compute initialization values to write to 
it is, it will follow each type "down" to leaf types using a 45 its base value. It is the data written by the New Value 
depth-first search. Handlo- that the Use Value Handler will read to create its 

In the example, "layerl" will be visited, then •layer2", refCon. 
and finally the original type *T' itself, ff the "layerl" type Only CMNewValueQ does this. The New Value Handler 
object had base types of its own, they would be visited is only for new values, but the Use Value Handler is used by 
before using 'Tayo-l" itself. Hence the depth-first search 50 both CMNewValueQ and CMUseValueQ. 
down to the leaf types. In the simplest case, with only one dynamic value, it can 

For each type processed, if it has a Use Value Handler of be seen that the data is written to the * Yeal" value. Now if 
its own, it will be called to get a refCon and value handler you layer another dynamic value on to this, the next chunk 
metahandler. of data is written using that layer's base value and hence its 

Note that this scheme allows total fi-eedom for the user to 55 handlers. The second layer will thus use the first layer's 
mix types. For example, type Tl could have base types T2 handlers. That may or may not end up writing to the **rcal** 
and T3. Alternatively, Tl could just have base type T2 and value depending on the kind of layer it is. If it's some sort 
T2 have T3 as its base type of I/O redirection handler (Le.. it reads and writes some- 

In the C++ class types shown above, note that each class where else), the second layer data will probably not go to the 
could have its own data along with its own constructor. The 60 **real" value. 

T class has a constructor that calls the constructors of all of The Use Value Handler is called both for CMNewValueQ 
its base classes. We can carry this analogy with the Con- and CMUseValueQ. The Use Value Handler reads the data 
tainer Manager just so far. Here is where it starts to break from its base value to create its refCon. If the user comes 
down. back the next day and does a CMUseValueQ, only tfie Use 

The problem here is that C++ class types are declared 65 Value Handler is called. Again it reads the data from its base 
statically. A C++ compiler can see all the base classes and value to construct the refCon and we're back as we were 
can tcll what data gets inherited and who goes with what before in the CMNewValueQ case. 
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It should be pointed out here that the Metadata and New 
Value Handlers will always be executed with a Container 
Manager running on some particular hardware (obviously). 
Jht data packet built from the CMNewValueQ • . " 
parameten is stored as a function of the hardware imple- 
mentation on which it is run (ie., whatever the sizes are for 
bytes, words, longs, etc.)* How it is stored is a function of 
the metadata returned from the Metadata Handler. In other 
terms, the New Value Handla has a contract with both the 
Container Manager and the Metadata Handler on the mean- 
ing of the parameter data. 

Note, however, it is not required that you be on the same 
hardware when you come back the next day and to the 
CMUseValue() that leads to the Use Value Handler call. Hie 
handles' writer must keep this in mind. Specifically, the Use 
Value Handler must know the attributes (bytes size, big^ttle 
endiaa, etc.) of the data written out by the New Value 
Handler so it knows how to use that info. In other words, the 
Use Value Handler has a (separate) "contract" with its own 
New Value Handler on the meaning of the data written to the 
base value. 

There is another, relatively minor, thing to keep in mind. 
That is that the value handlers for any one layer must take 
into account (he size of its own data when manipulating 
additional data created by the handlers for 
CMReadValucDataO, CMWriteValueData(), etc. This sim- 
ply offsets the write and read value data operations by the 
proper amount Remember all operations are on their base 
values. So if a New Value Handler writes data, this basically 
prefixes die **real" stuff being written by the handler opera- 
tions. 

The Metadata Handler is only needed for CMNewValueQ 
so that die prqjer number of CMNewValueQ 
parameters can be placed into a data packet for &e New 
Value Handier. The Metadata Handler must follow the 
prototype. 



CMMetaData xDetaData_Haudlei(CMiype type); 



where **type" is the (base) type layer whose metadata is to 
be defined. 

The Metadata Handler simply returns a C string contain- 
ing the metadata using the format descnptions described 
above. 

The type is passed as a convenience. It may or may not be 
needed. It is possible for a type object to contain other data 
for other prcq)eities. Types, after all, are ordinary objects. 
There is nothing prohibiting the creation of additional prop- 
erties and their values. This fact could be used to add 
additional (static and private) information to a type to be 
used elsewhere. For example, the type could contain a 
compression dictionary. 

The New Value Handler must follow the prototype, 



CMBookan iicwValue_Jfaiidlei<CMValue baseValue, 
CMTypetypc 
CMDataPacket dataPaclxt); 



where 

baseValue=the base value which is to be used to write the 

refCon data for the Use Value Handler 
type=the type corresponding to this New Value Handler 
dataPacket^the pointer to die data packet, created from 

the CMNewValueQ **..." parameters according the 

types metadata format description. 



12,879 

16 

The type is passed again as a convenience just as in the 
Metadata Handler. It can also be used here to pass to 
CMScanDataPacketQ to extract the dataPacket back into 
variables that exacdy correspond to that portion of the 
5 CMNewValueQ parameters that correspond to the 

type. It is not required, however that CMScanDataPacketQ 
be used. 

The Use Value Handler is called for both the 
CMUseValueQ and CMNewValueQ cases. If its con^)amon 
10 New Value Handler wrote data to its base value, the Use 
Value Handler will probably read the data to create its 
refCon. The ref Con wiU be passed to all value handlers. The 
Use Value Handler returns its refCon along widi another 
metahandler address that is used to get the value handle 
15 addresses. These are used to create the dynamic value. 
The Use Value Handler should follow the prototype, 



CMBoolean use\Uue_JIaDcUe3(CMWlue baseVatoe, 
CMiyp« type, 

CMMetaHandlex *iDstahaiKlleiv 
CMRefCon •icKZon); 



where 

23 baseValueMhe base value which is to be used to write the 
refCon data for the Use Value Handler 
iype=4he type corresponding to this New Value Handler 
metahandler^ pointer to the value operations metahan- 
dler which is returned by the Use Value Handler to its 
so caller 

refCon=a reference constant built by the Use Value Han- 
dler and returned to its caller. 
The baseValue and type are identical to the ones passed to 
the New Value Handler. The type may or may not be needed 
35 in the Use Value Handler, t I'lcft the Use Value Handler, it 
could be used to supply additional information from otfaex 
properties. 

It is expected that the Use Value Handler will read data 
from its base value to construct its refCon. The refCon is 

40 then returned along with a pointer to another metahandler 
that is used by the Container Manager to get the addresses 
of the value qperations. 

Note, both tiic New Value and Use Value Handlers return 
a CMBoolean to indicate success cs* failure. Failure means 

45 (or it is assumed) that the handlers reported some kind of 
error condition or failure. As documented, error reporters are 
not supposed to returiL But in case they do, we use the 
CMBoolean to know what happened. It should return 0 to 
indicate failure and non-zero for success. 

50 Value (Operation Handlers. The value operation handler 
routines can do a Container Manage CMGetValueRefConQ 
call on the value which was passed, in order to get at the 
refCon set up by the Use Value Handler. This provides a 
communication path among the value handlers. Further, the 

55 value handlo- should usually do its operations in terms of 
thdr base value, which can be accessed using the Container 
Manager CMGctBascValueQ call. 

The release handler is an exception to this rule. A set of 
one or more dynamic value layers arc spawned as a result of 

60 a single CMUseValueQ or CMNewValueQ. The layers result 
from the specified type having base types. From the caller's 
point of view s/he is doing one CMUseValueQ or 
CMNewValueQ with no consideration of the base types. 
That implies that the returned dynamic value should have a 

65 single CMRelaseValueQ done on it. The handlers have no 
business doing CMRclcascValueQ on their base value. This 
is detected and treated as an error. 
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A count is fcept by the Container Manager of every 
CMUscValucO and CMNcwValuc(). Calling 
CMRdeaseValueO reduces this count by one. When the last 
release is done on the dynamic value (its count goes to 0), 
the release handler will be called It is the Container Man 5 
agcr who calls the release handler fa- all the layers, not the 
handler. The Container Manager created them as a result of 
the original type; it is therefore responsible for releasing 
them. 

The reason the Container Manager is so insistent on 
forcing a release for every use of a dynamic value is mainly 
to enforce cleanup. Most value operation handlers will at a 
minimum, use a refCon that was memory allocated by the 
Use Value Handler. Release handlers are responsible fca: 
freeing that memory. In another example, if any files were 
open by the Use Value Handler, the releases would dose 
those fyies. 

A trivial value handler might merdy get its base value and 
use it to recursively call the Container Manager value 
procedure which initially invoked the handler to do its 
operation (again except for the release handler). In this case 20 
wliat it is basically doing is invoking the "inherited" value 
operatioa. In this case, the value operation could be omitted 
entirely by having ttie metahandler for the valuers type 
return NULL when asked for that value operation. The 
Container Manager uses that as the signal to search up the 25 
dynamic value inheritance chain to find the first metahandler 
that does define fiie operation. In the limit, it wiU end up 
using the original **real" value. 

Possible Limitations On Value Operations. Value 1/0 
operations are basically stream operations. That is, you read 
or write infonnation linearly fi:om a specified offset In 
addition, the Container Manager provides insert and delete 
value data API calls CMInsertValueData() and 
CMDeleteVakeDataQ. 

Insert and ddete can cause problems because base types 
may want to do certain transformations on their data that 
depend on what has occurred previously in that stream of 
data. For example, encryption using a cycHc key, or com- 
pression generally cannot be done singly by looking at a 
chunk of data starting at some random offset A cyclic key 
encryption can be deterministic if you can always determine 
where to start in the key as a function of offset But you can 
see that inserts and deletes will change the offsets of 
following data. You would not know where to start in the 
key. 

What all tiiis means is that certain data transformations 
only make sense if you are willing to refuse to support the 
insert/delete operations. Basically only data transformations 
that are position independent can be supported with the fuU 
set of value operations. 

Even sin^)le I/O to a file may aeate problems, since most 
file systems do not support inserts and ddetes in the middle 
of a file. If you do want to supp<Ht inserts and ddetes, then 
you should consider the potential for data intensive and/or 
coiiq)utationaUy intensive (derations. 
C. Format Overview 

A conceptual description of the Container Manager data 
format is now presented. As an overview, certain caveats and 
tricks are omitted at this Icvd which are covered in more 
detailed parts of this description. 

Rve key ideas underlie the Container Manager format: 

1) everything in a container is an object 

2) objects have persistent IDs, 

3) all the metadata lives in the TOC (Table of Contents). 

4) objects consist entirely of values, and ^3 

5) each value knows its own property, type, and data 
location. 
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The five ideas will each be discussed in turn. 

Everything is an object In a Container Manager 
container, every accessible byte is part of a value of some 
object. Even the metadata that defines the structure of the 
container, and the label of the container, are values of an 
object Type descriptions are objects, property descriptions 
are objects, etc We will exploit this fact in various ways 
below. 

Objects have persistent IDs. Every Container Manager 
object is designated by a persistent ID which is unique 
within the scope of its container. Objects may have addi- 
tional IDs and/or names that are unique in larger scopes, but 
this is not required. 

Object IDs provide a compact convenient way to refer to 
an object An efficient mechanism is provided to get firom 
any object ID to information about that object 

All the metadata lives in the TOC. This is a difference 
between fiie Container Manager and most other container 
formats, such as ASN.l, formats derived from IFF (such as 
Microsoft/IBM's RUT), etc. In these other formats, ttie 
metadata is associated with the chunks of data liiat it 
describes, a design approach that we call internally tagged. 
There are three reasons for this difference from other for- 
mats: 

a) The Container Manager embodiment described hcrdn 
is designed to support very flexible layouts, such as 
multi-media interleaving, and internal tags would be 
inconvenient and even harmful for ttiis. 

b) Applications inspecting an object can make dedsions 
about it more effidently if all of its metadata is con- 
centrated in one place, rather than being spread out over 
the container with its values. 

c) We want to be able to assimilate existing formats that 
contain collections of objects without fwchig them to 
change. This implies that we must be able to designate 
regions within the existing structure as values, without 
fcH'dng them to somehow retrofit internal tags. 

This approach to metadata does uiq)ose one significant 
design constraint A Container Manager container can only 
be read by starting with the TOC. This raises two questions; 
(1) how do we find the TOC, and (2) how do we access the 
TOC when we need information? 

1) In standard Container Manager containers the container 
label points to the TOC Possibly some non-standard con- 
tainers will exist that require other mechanisms. However, 
these will be exotic cases. 

2) Since we need to access the information in the TOC 
whenever we want to read a value, we have to have it 
available at all times. This normally means that the container 
needs to be on a random access device. 

If a container needs to be read on a device that docs not 
support effident random access (sudi as a CD-ROM) the 
TOC can be split up into sub-TOCs that sit in front of the 
groups of objects tfiey describe, and then the container can 
be accessed largely in stream order. 

Objects consist entirely of values. In the Container 
Manager, an object has no value as such. Each object has 
properties, and each property has values. The Container 
Managa: format provides no information about an object 
except its ID. . 

Of course, an object can have a single value; in that case 
the value of the property *is** the value of the object Thus 
the Container Manager format can easily accommodate tiiis 
"normal" case. 

Each value knows its own property, type, and data loca- 
tion. Each value consists of a property ID (or role), a type (or 
format), and data. For exan:q)le, a graphic object mig|it have 
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a value that describes its "dip mask"; the property ID would name using exactly the same mechanism^ and such object 

specify what role the value plays, but not what format it is names may be useful in some applications. 

stored in. The type would define how the mask is repre- Note also that objects can be given shoft names that are 

sented: rectangle, bit mask, path, Mac region, PostScript only locally unique, as in the RIFF TOC. These would be a 

path, etc. The data would be the Tq)resentation of the mask 5 different tj^pe than Globally Unique Names. 

Itself. Recall that type and property descriptions are objects as 

At the level of the container standard itself, there are no ^eU. Since types and properties need to have globally 

restrictions on what values an object can have, how many ^^^^^ ^^^^ ^ appHcations can recognize them, type 

values it can have, etc. However, individual object formats 1^^*=^ descriptions wiU typically have a globally 

may dictaterulesinthisarea.Ingeneral,appUcations should .o^mnc^^e vaiixt. fcmany cases, ti^ may be the only 

be prepared to encounter additional valu^ that they do not ^ ^^Pf ^ <lcscnption object 

J K A !u '^"^"""'r f "^^""*^f^"" """^ ""^ IQ some situations, however, we may wish to put more 

understand; these can be ignored. Tins aUows other appU. i^^^^tion into a dwctiption. Here are some ex^ples of 

cations to annotate objects wife additional values that may information that ^ be attached to types or proper- 
not be generally understood. Topically* these values will be 

associated with properties that are unknown to the applica- is gase types. As previously mentioned, base types allow 

^ ^ inheritance of semantics from other existing types for com- 

The data of a value is an uninteirupted sequence of bytes position into mare complex types. Such base type infonna- 

which may be from 0 to 2** bytes long, although these limits tion is intended to include uses such as encryption, 

may vary in a different embodiment This sequence of bytes compression, I/O redirection, etc. 

has no format requirements or restrictions. Furthermore, the 20 Encoding InfoimatLon. A type definition may indicate the 

byte sequences representing the data for various values of default encoding of its values. Typically, all of the values 

various objects can be placed anywhere in the container. with the same basic format in a container will have the same 

Thus there are no strong data format requirements for the encoding, so this new subtype can be shared by aU these 

container as a whole, although it must contain the metadata values. In this case the encoding can be indicated directly in 

to define its structure somewhere. 25 the type description for the format 

Special Cases. AU of the mechanisms above are consistent If values with the same basic format but multiple cncod- 

across all the uses of objects. However, there are two special ings exist in the same container, a more complex solution is 

cases that need to be considered. required. In this case, a subtype may be created just to record 

First, The Container Manager format allows a single the encoding. Such a subtype will typically not need a 

object to have multiple values with the same property ID. AU 30 globaUy unique name. 

the values must have different types. Such multiple values Conqiression information. In addition to the compression 

are intended to be used as alternative representations of the technique, typically recorded via a base type, the type can 

same information. record compression parameters, the codcbook used (if 

Second, the table of contents can contain muUq)le entries applicable), etc As with encoding information, a type that 

for a single value. These entries mean that the value rejEc- 35 exists just to record conq)ression information typically wiU 

sented by the entry is actuaUy stored in multiple segments. not need a globaUy unique name. It wiU refer to the 

This permits values to be broken up into chunks and underlying format type and the conqiression technique, both 

interleaved, without creating problems for appUcations tiiat of which wiU have globally unique names, 

view them as single values. In addition, it aUows an appU* A template or grammar for a type. This aUows appUca- 

cation to build TOC entries that "synthesize" a value out of 40 tions that have never seen this type before to parse values of 

separate parts, as is required in retrofitting some file formats. that type and potentiaUy get some useful information out of 

Note that these two special cases can be mixed fircely. A them. Examples of description mechanisms that could be 

property can have multiple values, and one or more of the used in this way are ASN.l and SGML. The more general 

values can be composed of multiple segments. type wiU be indicated as die super-type. For exan9>le, a 

Other Issues— <jlobaUy Unique Names, To fulfiU the 45 given SGML DTD as a type wiU have a specific SGML 

lequirement for locaUy generated unique names for types definition of tiie DTD. The super-type of tfiis type would be 

and properties, the Container Manager embodiment SGML itself, which defines the basic encoding conventions, 

described herein supports identifiers defined in ISO 9070. Method descriptions for a type. A type could have prop- 

These are names that begin with a naming authority erties that provide method definitions, l^oviding methods in 

(assigned to a system vendor or an application vendor), and 50 the container would aUow fuUy encapsulated use of values, 

then continue with a series of more and more specific D. Format Definition 

segments, until they end in a specific type or property name. The concrete format of the table of contents (TOC) of a 

While another embodiment can use a different naming Container Manager container wiU now be described. The 

convention, names generated according to ISO 9070 are TOC consists of a sequence of entries. Each entry corre- 

both unique and self-doounenting. Individual users can 5S spends to a single segment of a value of some object 

generate unique names using this approach. For example, a TOC entries are sorted by object ID, and within a single 

user developing educational stackware might want to create object they are sorted by property ID. Thus aU the entries for 

properties, or even types, to use in scripts. The stackware a given object are contiguous in the TOC, and aU the entries 

development environment could automaticaUy generate a for a given property are contipous within the object Also, 

unique prefix for the usct, based on the serial number of the 60 an object can be found within the TOC, or a property can be 

development tool, and then append the user generated prop- found within an object, by binary search. If an object ID or 

erty or type name. a property is not de^ed, we can quickly determine that it is 

This ensures that if that user's scripts and data are not defined, 

combined in a container with other information generated by Thus, each object in the container is represented in the 

other users, no naming conflicts can occur. 65 TOC by a sequence of entries, one for each segment of a 

Note that globaUy unique names are not limited to prop- value of the object. The Container Manager has no way to 

crty and type descriptions. Any object can be given a unique represent an object without at least one value. 
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Since each TOC entry defines a value, we know imme- main memory storage areas, which pointers refer to other 

diatcly that it must indicate the object ID, property, type, and structures in memory in a known manner which is defined by 

data of the value. In addition, it indicates the generation the data structure. Thus a data structure, as used herein, is an 

number of the value in order to allow applications to check abstract description of the organization of data in main 

consistency between different properties. The TOC entry 5 memory 304; when the data structure is "ercated* in main 

may also contain bookkeeping information for the value. memory 304, this description is imposed on regions of main 

Hie object ID field in a TOC entry identifies the object memory 304 so that spcdfic items of infonnation can be 

that this value is part of. The property field identifies the found and/or interpreted according to the data structure. The 

value's property by the object ID of a property description. terra '^pointer", as used herein, is a well-known shoothand 

The type field indicates the value's type by the object ID of lo for physical signals which are stored as charge, current or 

a type description. voltage levels in the memory cells whidi implement the 

The entry indicates the value's data by the offset and main memory 304, These signals **idcntify" an item of 

length of the sequence of bytes representing the value. The information memory 304 in the sense that, when applied to 

offset is a 0 origin byte offset from the begiiming of the the memory 304 as an address (either directly or via an 

container. The length is a byte count, and may be 0, 15 address translation mechanism), they cause the memory 304 

indicating a 0 length value. JS the data is four bytes long or to read out data from the item pointed to or identified by such 

less, it may be included directly in the TOC as an immediate signals, 

value, rather than being referenced by offset and length. Also, it will be understood tiiat even though different 

A TOC entry could simply be defined by putting all the types of computer systems inclement schemes such as 

information above in a record. This record would be rela- 20 caching and virtual memory, in which some of the data may 

tively large, however, and would be very likely to contain not actually be located in main memory 304 itself at various 

redundant and/or unused information. The presently timcs» these mechanisms are transparent to the Container 

described Container Manager embodiment therefore uses an Manage embodiment described herein. Thus, the data is 

approach in which each TOC entry contains only the infor- referred to herein as being located "in" main memory 304, 

mation that is new or different compared with the previous 25 even if it is actually, transparently, located elsewhere. 

TOC entry. This results in a TOC that is organized as a B. In-Memory Data Structures 

stream radier than a table, and is parsed as it is read in. The FIG. 4 is an overall block diagram of the major data 

acmal format of the TOC is not important for an under- structures which are created in main memory 304 during die 

standing of the invention. pendency of a "session**. Data block 402 is a "session global 

Note that every TOC contains a standard object that is 30 data" block containing all of the session-wide data for a 

used to describe die TOC itself. In particular, it is object ID given Container Manager session. There is no static global 

1, so the TOC entries for die TOC itself always come at the data in the code. All open containers are tied to the session 

beginning of the TOC. (Object ID 0 is never used). Addi- on a doubly linked list whose head and tail pointers are 

tional TOC properties can be useful. For example, an index contained in the session global data. The root of a meCah- 

to speed access to the entries by ID could be attached to the 35 andler table 404 (described below) is kept here as well along 

TOC through another property. Potentially several such with the session handler pointers for malloc, fi^c, and error 

indexes, using different f<xmats, could be attached. reporting. 

Object IDs other than IDs of standard objects are gener- Containers are identified in the session global data block 

ated by sequentially incrementing a counter from 402 by a pointer to the container's Container Control Block 

0x000 ICXKX). Object IDs are never reused in later genera- 40 (CCB). Each time a container is opened with 

dons of a container if an object is deleted. The last ID CMOpcnContaincrO or CMOpcnNcwContainer(), a new 

number generated is kept as a property of object #1 to allow container control block 406 is created. The pointer to the 

generating further IDs without reuse. container control block 406 is what is returned to tfie user as 

IL IMPLEMEOTAnON ^ container *VefNmn'^ (reference number). 

45 There are five primary data structures tied to the container: 

A. Hardware Pour are shown in the diagram and are discussed later. The 

The Container Manager of the present embodiment is fifth is the **toudied chain'*, used for recoiding updates. The 

implemented entirely as software instructions and data, to be **touched chain" is not important for an understanding of die 

executed on general purpose con^jutcr hardware. No spe- invention and is not described herein, 

dfic hardware platf cmn is required. For coixq}leteness, 50 The four shown main data structures pointed to from the 

however. HG. 3 illustrates a typical hardware con^)Uter container control block406 are the list 408 of deleted values 

system platform on which die Container Manager might run. (TOCValueHdr(s)), a List 410 of embedded container 

The con[q)uter system of FIG. 3 con^nises a CPU 302, pointers, the global name symbol table 412, and a pointer to 

main memory 304, which may be volatile, an I/O subsystem a TOC 414 control block 416. 

306, and a display 308, all coupled to a CPU bus 310. Hie 55 The table of contents (TOO 414 is die set of related data 

VO subsystem 306 communicates with peripheral devices structures that organize objects by object IDs. The require- 

induding persistent storage devices, such as a disk 312. In ment that objects be kept in sorted order (sorted by object 

typical <q>eration, an ^plication program, together with at ID) puts certain constraints on its organization. Furdier, the 

least those Container Manager routines which are used by fact that the IDs are generated sequentially in new containers 

die application program, are retrieved from the disk 312 into 60 also must taken into account (for example, binary trees 

main memory 304 for execution by the CPU 302. All of the would not be a good choice in such a situation), 

data structures described below arc also created in the main The method used in the Container Manager of the 

memory 304, in the sense that memory space is allocated for embodiment described herein is an index table algoithm. It 

die infonnation to be contained in the data structures, and all is somewhat memory intensive but allows objects to be 

of the software routines which read or write to such memory 65 accessed linearly in time and keeps the objects in the 

locations do so according to some known definition of fields. required sorted order. The index tables correspond to **pow- 

In addition, pointers arc written to certain of die allocated crs" of a diosen index table size. For example, if die table 
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size is 256 and the mfraiTniim ID is OxFFFFFFFF (32-hits As used hcrdn, a "header" for an item or items of 

unsigned on MC68XXX machines) the access depth will be information is a logical collection of information which 

4 for any ID, applies generally to the item or items. The header need not 

To illustrate this, if we had ID 0x00123456 we would be physicaUy located in a contiguous region of memory, nor 
have 4 indices: 0x00, 0x12, 0x34, and 0x56. Four index 5 must it be contiguous with any of the items themselves, 
tables would exist each corresponding to the indices 00 to Each TOCValue 426 can be d&er immediate, non- 
OxFF, i.e., mod the size of an index table. Each index is used immediate, or a global name. Inmiediate values contain 1, 2, 
to index into its corresponding index table. Thus, in this or 4-byte value data encoded directly in the entry. Non- 
example, the first table would have its OxOO'th entry point- immediates contain a container offset to die value data and 
ing to the next tabic. That next table would have its 0x12 lO its length. Non-immediates can also represent dynamic 
entry pointing to the third table. The third table would have values (dismissed below). Global name values, such as 428, 
its 0x34 entry pointing to the last table. The 0x56 entry in are pointers to global name symbol table entries (discussed 
the last table would point to the actual object with ID shortly) and once the value data has been written to the 
0x00123456. container, the container offset. 

Continuing with this exan4>le, if every ID possible were 15 Note the diagram shows, in addition to the doubly linked 

represented, then there would still be only one top level liststructures, a pointer for each TOCValue back to its value 

table. But there would be 256 second level tables corre- header. Similarly, each TOCValueHdr has a pointer back to 

sponding to the 256 level-one indices. Each of those 256 its TOCProperty. Finally, each TOCProperty has a pointer 

level-two tables would have pointers to 256 level three back to its TOCObjecL Not shown is a pointer from each 

tables and so on down to level 4. 20 TOCObject and each TOCValueHdr back to its container 

Fortunately, new containers are generated with sequential control block. The result is that anything can be accessed 

IDs so that only die minimum number of tables is required from almost anywhere and in any direction. 

But if a new nonsequential number is needed the requisite When a CMRegisteiTypeO or CMRegisterPropatyO is 

new tables are generated as needed to go from the top level done, a check must be inade to see if the spediied global 

table to the lowest level table. 25 name already exists. For this, a simple binary tree symbol 

The routines that maintain this data stmcturc are gen^- table 412 is used. Since a global name is itself a type or 

alized to support any size table (within limits). There are property object value, there is also a pointer from a 

trade-offs between table size and access time, which are TOCValue to the name in the global name symbol table, 

apparent to a person of ordinary skill. Each global name symbol table is unique to its container. 

Because ofthis generalization, aTOC has associated with 30 Hence the contains control block has the root to its tree of 

it all the variables that are needed to manipulate the Index global names. 

tables. This is kept in TOC control block 416, pointed to Whenever a container is opened a set of predefined global 

from the container control block. The TOC control Mock names is generated. Basically the equivalent of 

416 is to TOC object access, what the container control CMRegisterTVpeO and CMRcgisterPropertyO is done but 

block 406 is to the entire container. 35 the object IDs are standard rather than user IDs. 

The TOC control block points to another data structure Note, global names are not written to die container at the 

not shown here to keep the drawings simple. It is a set of time they are created. Instead they are k^t in the global 

dircc head/tail list pointers to doubly linked lists of the name symbol table. When a container that was open for 

T0CObject(s). The three lists are for all the objects, property writing is closed, the global name symbol table is '*walked" 

objects, and type objects in the container. Thus the type and 40 and all user defined names written to die container. At that 

property lists are subsets of the object list These lists are point the TOCValues associated with global names arc set 

only just for the CMGetNextxxx() routines. These lists are with the container offsets for those names. This is done using 

kept as part of the TOC since, there can be only one TOC and the back pointer from each global name entry to its 

one of these list sets. Note that for updating, there can be TOCValue. The TOC is dien written followed by the labeL 

multiple containers using the same TOC, so putting these 45 Since the TOC is written after die global names, all die 

data structures here is the most convenient way to deal with global name offsets will be set by that time. Thus everything 

them during updating. is correct when the container is to be read. 

Note, that since there can be multiple users of a TOC, a The Container Manager of the presently described 

TOC requires a **use count" to prevent premature release of embodiment supports embedded containers. Embedded con- 

theTOC. 50 tainers are treated just about like any other. The main 

The lowest level of the TOC index tables 418 contain difference is diat they require a special handler that writes or 

pointers to die container objects themselves instead of to reads (CMWriteValueDataO and CMRcadValueDataO) to a 

other index tables. These objects are TOCObjects 420. The value that belongs to the parent container. The handlers 

TOC entries for an object arc linked off of their TOCObject kseps track of offsets with the value that it is treating as a 

TOCObjects are returned to die user as object refNums 55 container. 

(CMObjcct, Onypc, and CMPropcrty). The effect is to write or read a parent value as if it was a 

The properties, TOCProperties 422, for an TOCObject are container. All die data for the parent value is created as a 

contained on a doubly linked list off the TOCObject. The container, complete widi its own TOC and label. The offsets 

values f CH- each property are on a doubly linked list of value in die TOC arc relative to the start of die value, offset 0, just 

headers, TOCValueHdrs 424, off of each TOCProperty. 60 asinthenon-embeddedcase.Thismeanstfiat a parent value 

Finally, a specific real (as opposed to dynamic) value, such could be read to copy the container as is. 

as one of the TOCValues 426, is linked to its TOCValueHdr, Aside tnm die special handlers, most of die odier stuff 

The reason die values are linked to a value header is needed to open and close a container is independent of 

because of continued (multi-segment) values. A multi- whedier it is embedded or not. There are a few wrinkles, 

segment value can have more than one value entry. Hence 65 however. First, a container can have any number of embed- 

tiie chain. Also, it is pointers to value headers diat are ded containers open at the same time. Eadi of diose could 

returned to the user as value refNums (CMValue). also, and so on. The result is essentially a tree of open 
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embedded containers. Since the data for a parent value is its 
embedded container, then if there arc any more deeply 
embedded containers, they would also be part of the parent's 
value. This gets very confiising if you try to think of it more 
than two levels deep. 5 

In all cases, when a parent is dosed, we want to close all 
of its descendants. 

The embedded container list 410 pointed to from the 
container control block is used so that a parent container can 
keep track of all of its immediate descendants. Each entry in 
the list is simply a pointer to a descendent container control ^ 
block. At open time an entry for the embedded containa: is 
created in its parent embedded container list. At dose time 
CMaoseContainerO will go through its list of embedded 
containers (ie., the list of its immediate descendants) and 
recursively call CMaoseContainerQ to dose those. The net 
result is the desired one of dosing all the descendants of the 
parent in the tree of embedded containers. An embedded 
container being dosed is responsible from removing itself 
from its parent's embedded container list so that it won't be 
"seen" again if a parent further up the tree is closed. 20 

Note, the functionality of embedded containers can also 
be done using dynamic values. However, the Container 
Manager^ not being aware of this use of dynamic values, will 
not maintain the embedded containers list for it Thus each 
dynamic value coiresponding to an embedded container 
must be explidtly "closed" using CMRdeascVaiue(). 



The solution adc^ted is to put all ddeted objects and 
values on a list of ddeted items assodated with the con- 
tainer. There are two lists: list 430 for objects pointed to 
from theTOC control block, and list 408 for deleted values 
pointed to from the container control block itself. 

Note, since object refNums are TCKIObjects. and value 
refNums are TOCValueHdrs, the only thing needed on these 
lists are those data structures. TOCPtoperties and TOCVal- 
ues can be freed. The TOCC»3jects and TOCValues are 
flagged as "ddeted". Whenever any object or value is passed 
to the AH it is checked for the flag, ft is an error to use a 
deleted item. 

CMSctMetaHandlcr<) is called by the user to record 
metahandlei/^pe name associations. Hicse are maintained 
in binary tree symbol table 404. The root of this tree is a 
**global" in the session data, ft is not tied to any one 
container. When a container is opened, a type name is 
passed. This is used to look it up in the metahandler symbol 
table. This yields a metahandler function address which in 
turn is used to get actual handler routine addresses. 

The following C-language stract defines the layout of all 
in-mcmory TOCObjects. The objects arc accessed by thdr 
object ID. 
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stiuct TOCObjcct { 

CMObjectlD objccOD; 
listHdr pCDperQrList; 
struct Container ^coot^ner; 
struct TOCObject ♦nextObject; 
struct TOCObject *prevOb5ect; 
struct TOCObjcct *c«lfiypeProperty; 
struct TOCObject *prevT5fpeProperty; 
imsigTHvl short objecO^hgs; 
CMRjbtCon objectRefCon: 
unsigned long useCount; 
struct TOCObject *iKxlTouct^Objcct; 
listHdr touchedLiat; 

}; 

typcdcf stiuct TOCObject TOCObject, ^TOCObjectPtn 



/• Layout of a TOG otiject */ 
/* the object's ID (keep first for debugging) */ 
/• list of object property entries •/ 
/• ptr to "owning?* ronfainrr control block ♦/ 
/« chain to next object by incieasixtg ID */ 
/* chain to pievious d^ect by decxeaang ID */ 
/* chain of next type/prepetty by increasing ID */ 
/* chain of previous typt/ptoperty by deer. ID */ 
/♦ info flags about the object •/ 
/* user's object refCon */ 
/* count of nbr of times **used'* */ 
/* link to next touclvd object */ 
/* vahies^ptoperties touched IN this object * 



The following object flags are defined: 
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^define UndefinedObject 
#define ObjectObject 
#defiDe PropeztyObjcct 
#define TypeObject 
Ikkfioe DeletedObject 
#defiiie DynanucValuesObject 
#deaDe IbuchedObject 
#defiiie ProtectedObject 
«defiiKi LinkedObject 
#defii» UndefObjectCounted 



QxOOOlU /• 1 => object created but xaKfcfimi*/ 

Qx0002U /* => object is a base object ♦/ 

Ox0004U /* =^ object is a property (kscriptor*/ 

QxOOOSU /♦ =0 object is a type dwciiptor*/ 

GxOOlOU /* =^ object has becQdcktcd*/ 

QxOSOOU /♦ ==> object "owns** dynamic valiKs'/ 

QxlOOOU /* =0 object has been -toTKherf' •/ 

QX2000U /» =^ object is tocked/piotected •/ 

0x400011 /* ^ object linked to master lst$*/ 

QxSOOOU /• =^ object comted as uulefizKd */ 



When CMDeleteObjectO is called, an object is to be ^ 
deleted. When CMDeleteValue() is called, a value for a 
property of an object is to be ddeted. As mentioned above, 
the refNums for objects (CMObject, CMProperty, and 
CMValue) are pointers to TOCObjects. Values (CMValue) 
are pointers to TOCValueHdrs. Thus we cannot truly delete 
the items (i.e., free their memory) these point to because 
there is no reliable way to verify that the pointers arc valid. 



Note that the properties 502 and 504 in the object of FIG. 
5 are described by property descriptors which are them- 
selves objects which follow the above layout The layout of 
each of theprqjerties 502.504 and 542 is defined as follows: 
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struct TOCPtoperty { /• Layout of a TOC object property: •/ 

LisUnlcs propertyliiiks; /* Unlcs to next/ptev property (must be first) */ 

TOCObjectPtr tiKObject; ;* ptr to **owmog** object ♦/ 

CMObjecOD propeitylD; /* the property's ID V 

ListHdr valueHdd^ist; /* Est of property's vohies */ 

}; 

typedef struct TCX3*ioperty TOCPropeity, *TOCPropcityPtT; 



TVpcs, too, are described using objects of the TOCObject 
form set out above. The structures of TOCValueHdrs 424 
and TOCValues are set forth hereinafter. 

As previously mentioned, the Container Manager routines 
CMNewValue 0 and CMUseValue Q create a dynamic value 
chain for each type &at has a "UseValue** and a '*NewValue'* 
handler. FIG. 5 illustrates the structure of in-memoiy objects 
which are aeated by the dynamic value mechanisuL 

Referring to FIG. 5, it is assumed that one of the TOCOb- 
jects 420 (ftG. 4) has a scries of properties 502, 504, and so 
on (conesponding to 422 in FIG. 4). It is assumed further 
that property 502 has two values associated with it, indicated 
by value headers 506 and 508 (424 in FIG. 4). These values 
are of different types, as wiD be seen from the fact that 
different dynamic value diains arc created for these values. 
Property 504 also has values associated with it but these are 
shown only in the abbreviated form of an arrow 510. 

Associated with real value header 506 is a segment 512 of 
real value data, and associated with value header 508 are two 
segments 514 and 516 of real value data. If the values for the 
property 502 were not of types which require creation of 
dynamic values, then the actual data of the values would be 
stored in segments 512, 514 and 516. Since the type of these 
values call for dynamic value creation, however, the data 
stored in real value data segments 512, 514 and 516 may 
instead be transformed versions of the actual data and/or 
may contain only indirection information. 

The value header structure includes a pointer to the top 
dynaniic value header 518 in a chain of dynamic value 
headers 518, 520 and 522. Each of the dynamic value 
headCTS 518, 520 and 522 have a format which is identical 
to the value header (also called a '*real value header*') 506, 
except that the field in real value hcadCT 506 which pointed 
to dynamic value header 518, is redefined in dynamic value 
header 518 to point to a set of dynamic value header 
extensions 524. The extensions 524 include an entry which 
points to the base vabie of the dynamic value header 518, 
which in the case of this chain, merely points to the second 
dynamic value head^ 520 on the chain. Dynamic value 
header 520 in turn points to its own dynamic value header 
extensions 526, which in turn points, in the base value field, 
to dynamic value header 522. Dynamic value header 522 
also points to its dynamic value header extensions 528. But 
since dynamic value header 522 is at the bottom of the chain, 
its base value is the real value data stored in segment 512. 
Thus, the "base value" field of extensions 528 points back to 
the real value header 506. 

Recall that tiie purpose for creating a chain of dynamic 
value headers 518, 520 and 522 is to implement a complex 
value type which transparency handles data transformations 
and redirections. Each of the dynamic value headers 518, 
520 and 522 corresponds to a respective one of the types on 
the tree defining the complex t^ of the value headed by 
real value header 506. Thus, each of the dynamic value 
headers 518, 520 and 522 maintains its own vector of value 
handlers to be used when a higher level caller desires to 
invoke a value operation. These dynanoic value vectors are 
illustrated in FIG. 5 as 530, 532 and 534, pointed to 
respectively by extensions 524, 526 and 528. The dynamic 



value vectors 530, 532 and 534 contain a series of pointers 
to the respective value handlers to be called. TTie pointers are 
in predefined locations in the vector, for exas^e, the third 

15 entry in each vector contains the pointer to the WriteValue- 
Data handler to be called for a value data write ox>eration. 

The value header 508 in FIG. 5 is for a value whose type 
spawned only a single dynamic value header 536. Thus, the 
value header 508 points to dynamic value header 536, which 

20 in turn points to its extensions 538, which in turn points both 
to a dynamic value vector 540 and, for the base vatoc, back 
to the value header 508. 

When a real value spawns dynamic values, a special 
dynamic value property 542 is created only to contain the 

25 (tynamic value headers. Only the bottom most layer of each 
dynamic value chain (the layer whose base vahie is the 
**real" value) is on the dynamic property chaia All higher 
layers are not part of tfic dynamic property chain. The 
dynamic value property chain is used to simplify deletion of 
dynamic values, for example when the container is to be 

30 dosed. 

Dynamic value headers never have value segment lists. 
No data is ever written to a dynamic value because these 
headers are removed when the value is released using a 
CMRdcaseValueO. If there is any data, it must be associated 
35 with a **real" value— the real value associated with a 
dynamic value or some place else. 

In each value header there is a pointer (a union called 
"dynValueData" with alternative fidds called "dynValue" 
and "extensions") that contains three possible values: 
40 1. dynValueData is NULL for **real** value headers that 
don't have a corresponding dynamic value. 
2. dynValueData.dynValue is a pointer to the top-most 
layer if it is a '^al" value that docs have a correspond- 
ing dynamic value header. 
45 3. dynValueData.extensions is a pointer to the extensions 
if it is itself a dynamic value header. 
The value header's flags determine how to interpret the 
pointer. 

When a dynamic value is spawned by CMNewValue() or 

50 CMUseValueO, the pointer to the top-most dynamic value 
header is returned as the refNimL That means whenever tiie 
user passes it to an API value routine, it will dicdc to see if 
the refNum is a dynamic value. If it is, it initiates the call to 
the corresponding value handler using the vector in the 

55 extensions. That may cause a seardi up the base value diain 
to look for the inherited value routine. In the limit, the 
original API value routine is used if no handler is supplied 
and the '^real** value in the chain is reached. That's how data 
could get in there. 

60 FIG. 6 illustrates the same structure as FIG. 5 using a 
simplified notation. This notation will make it easier to 
describe how dynamic values are spawned and layers cre- 
ated. Here "0" is object, 'T" is property, "VIT* real value 
header, 'TDVP** the dynamic value property, and "DVH*' a 

65 dynamic value. The value segments are omitted. 

As previously mentioned, when a CMNewValuc() or 
CMUseValueO is almost done, a check is made on the 
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value's type, and all of its base types (if any) to see if it has 
an associated registered metahandler. If it does, it is called 
with a •'use value" operation type to sec if a **usc value" 
handler exists for the type. If it does^ the dynamic value is 
spawned. Thus if CMNewValueQ or CMUseValueQ sees 5 
any (base) type that has an associated '*U5C value" handler, 
it will spawn a dynamic value. 

The spawning is done essentially by calling the '*use 
value" handler. It is expected to set up a refCon to pass 
among the value handlers and a pointer to another metah- lo 
andler. These arc returned to CMNewValue() or 
CMUseValue() which uses newDynamicValueQ to do the 
actual creation of the dynamic value. The extensions are 
initialized, the metahandler pointer saved, and the refCon is 
also saved. The pointer to the created dynamic value header 15 
is what CMNewValueO or CMUseValueQ returns to the user 
as the refNum. 

When the user atten4>ts to do a value operation using this 
refNum, a dieck is made that the refNum is for a dynamic 



Internally, the t object can be represented as shown in 
FIG. 7 (using the notation of FIG. 6). The value data 
segments are shown here with the data the segment will 
point to in the container. 

For the t object 702. the ^obal name property 704 and 
value 706 are created, as usual by calling CMRcgisteiType 
(). The CMAddBaseiypeO calls add the base types. These 
are recorded as the object IDs for each base type in the order 
created as separate value segments 708, 710 for a special 
"base type" property 712 belonging to the type object 702. 
The value segments 708, 710 store only the Object IDs of ttie 
base types; the global name of the base types are stored as 
values such as 706 in respective type objects similar to 702. 

As mentioned above, CMNewValueQ or CMUseValueQ 
spawn dynamic values if the original type or any of its base 
types have an associated %sc value" handler. Assume that 
was done for T in the above exanqde. What happens is that 
CMUseVALUEO or CM'scValueQ wiU look at its type 



value. If it is, the corresponding handler routine will be 20 ^^i^^ *° ^ee if the base type property is present If 



called. The vector entries are set on first use of a value 
operation. It may mean searching up the base value chain, 
but once found, the handler address is saved in the top layer 
vector (associated with the refNum) so the search doesn't 
have to be done again. 

Note that if the search must be done up the base value 
chain, then the dynamic value refNum (pointer), in addition 
to the handler address, must be saved. This is very much like 
C++ classes, where inherited methods are called and the 



it is, it will follow each type "down" to leaf types using a 
depth-first search. 

In the example, layerl will be visited, then layer2, and 
finally the original type T itself. If the layer 1 type object had 
25 base types of its own, they would be visited before using 
layerl itself. Hence the depth-first search down to the leaf 
types. 

For each type processed, if it has a **use value" handler of 
its own, it will be called to get a refCon and value handler 



appropriate **this" must also be passed. The "this" in this 30 metahandler. These are passed to newDynamicValue() to 



case is the refNum 

Previously there was described a layered type T which 
was registered in the Container Manager with its two base 
types Layerl and Laycr2 as follows: 



layerl ^ CMRegistfiTypc(cc2iitainer, "Layerl"); 
layer2 = CMRe£jstcrt:ype(cactainct, XaycrZ"); 
t = CMRegistei'^Tpe(contaiiier, *T'); 

CMAddBasel^t, layerl); 
CMAddBasel^Ct, layer2); 



35 



40 



create a dynamic value for the original **real" value. 
newDynamicValueQ always returns its refNum that will be 
the dynamic value it created. The first layer will create the 
dynamic value property and put the dynamic value header 
on its value header list. All further calls to 
newDynamicValueQ will pass the most recent refNum 
returned from it newDynamicValueQ then chains these off 
the first dynamic value header. This produces the desired 
layering result. 

The following C-language code defines TOCValue, the 
format of one of the TOCValue data segments 426 (FIG. 4) 
or 512, 514, 516 {FIG. 5): 



® 1992 Apple Computier, Inc. 



unicin TOCWueBytes { 
struct { 

CM^ULONG value; 

CM^ULONG vahicLea; 
} DDtImm; 
struct { 

CM^ULONC ofifact; 

struct GlobalNaiDe *globalNaziieSymfaol; 
} globalName; 
uiiiQn{ 

CM^UCHAR achais%lac[2*sizeof(CM_lILONG)l; 
CM_XJLONG uksngViaae; 
CM_USHORT usbo^t^^ue; 
CM_UCHAR ubyteVahie; 
void 'ptrValue; 
} hmn; 

}; 

typedef unioQ TOCValueBytes TOC\^\MBytes, nOCVatuaBytesPtr; 

struct TOCV^ { /♦ Layout of a TOC type's vahie: */ 

ListLinks vahaeLinks; /* link* to ocxt^prcv value (must be first) ♦/ 

struct TOCVdueHdr ♦thc\WueHdr, /* ptr back to VahieHdr "owning" this vahic */ 

ContaincrPtr comaincr; /• ptr to "owninj^' container control block •/ 

CMVahieFla^ flags; /* flags ♦/ 

TOCWuefiytes value; /« value and length or immediate value •/ 

un^gned long LogicalO&et; /* original (unc(£ted) Logical offset */ 



/* Layout of value/Length &kls; «/ 

/* value if not iinmediate(not expbcidy here): */ 

/* offset to value if not tmTTiM;at<> */ 

/* value length if not imTn^A'a^^ •/ 

/* value fisT a gbbal name */ 

/* ofiEset to value in container */ 

/* ptr value for a gkibal name (in memory) */ 

/* actual value if t unr nr di a^*^ placed here: */ 
/* vahie if immediate »in!«'g Twt chax(s) */ 
/* value if immediate rniggrw^ kwg '/ 
/* vahie if immediate ™gtgfwi short V 
/* value if imnw^jy^y unsigned byte */ 
/* vahie if imnfiH i^ tr pointer */ 
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}; 

typcdef stmct TOCValue TOCVWue, rKX: WuePtr, 
enum ConstValueTypc { 

"^lucL-NotlnuD, 

ValucL-GlobalName, 

Valuc_Jmin_Chais, 

Value_ TniTTi^Sbort, 
Wue_Imia_3yte 

}; 

typcdef enuxa ConstVahio'iypo ConstValueTypc; 



I* Data types used to copy data into TDCVal- 
ue's: */ 

/* not immediate ^> value and vahieLen */ 
/* gtobal name ptr =i> in-inemoiy str ptr */ 
/• immediate, chars =^ ucharsValue »/ 
/« immediate, long =^ vloiigValue */ 
/* immediate, sbort =^ ushoitValiie */ 
/* immediate, byte => ushortWue •/ 



15 



The following C-languagc code defines the format of a 
Value Header (both real value headers and dynamic value 
headers). 



@ 1992 Apple Computer, Inc. 



struct TOCVahieHdr { 

LtstLinks vahidUiLinks; 
struct TOCPropcrty •ttePropcrty; 
ListHdr valucList; 
CMObjcctID typdD; 
ContainerPtr containeT; 
unsigned lan£ si3se; 
unsigned long logicalSize; 
unsigned sboit valuePhgs; 
CMGeoeration generation; 
unsigned Icnxg useCount; 
CMRefCon valueReiCon; 
TouchedUstEnliyPtr touch; 
union { 

struct TOC>^aueHdr *dyiiV^hje; 



/* Layout of a TOC property type: */ 

/« Links to next^rev value hdr (must be first) */ 

/• ptr to "owning" property */ 

/* fist of actual values V 

/* the valtK's type ID */ 

/* ptr to "owning* container omtrol block */ 

/* total anreDt size of the value data */ 

I* anginal (umipdated) size of the value data */ 

/* flags indicating stuff about the value */ 

/* generation number V 

/• count of nbr of tinKs •used" */ 

t* user's value TefiC!on •/ 

ptr to updating touched list eotiy */ 
/* this field depends on kind of vaiue hdr */ 
/* ptr to dynamic value hdr or NULL */ 



stmct DynWueHdrEit ^extensions; /* ptr to dynamic value hdr extensions 



}: 



} d^nVahieData; 
union { 

TOCObjecfPtr refDataObject; 
ListHdrPtr refShadowList; 
} references; 



/* [extensions on^ when it*s a dynamic value] */ 

/* refereDces xeocvded by this value *f 

J* associated zef object; KUIX if no refs */ 

y* or shadow fist of the actual data */ 

/* (refShadowList only in recording value) */ 



typedef struct TOCVahieHdr TOCVahacHdr, n'CXJ^hieHdiPr, 



/* Extensions to TOCValueHdr fior a dynamic value: */ 
/* ptr to base value of this dynamic value */ 
/* dynamic value handler vector */ 
/* metahandler to get handler addresses*/ 



struct DynVahvHdiExt { 

TOCValueHdrPir bascValue; 
DynamicVaIue'\tetor dyaValue\bctDi; 
CMMetaHandlcr metaHandler, 

}; 

typedef struct DynVahvHdiExt DynValueHdiExt, *I>ynValuefldrExlPtr, 
/* Some of fbUowing vahieiFlags echo the fl^s field a TOCValue entry. That is because a 
CMVahie *^fi^unr that an API user is ^en axxl in turn given back to us is a pointer to a 
TCXTValoeHdL It is sometimes more convenient therefore to check the kind of value we have 
by looking at the header then "gomg ouT to the value. In all but contmued values there 
is only one TOO^hie entry on the valucList anyway. So echoing is more efi&cient then 
always going after the tail or head (they're the of a vataieList just to see the flags and 
the kind of value. */ 



#defineVahieDeleted 


OiOOOlU 


/• 


valueFlags: 1 => deleted vahie */ 


#defiiK ValueContinued 


CKX0002U 


/* 


=> continued •/ 


#defineValueGlobal 


OX0004U 


/• 


=> global name •/ 


^define Vgiwiyipify^jjate 


OxOOOSU 


/• 


=> immetfiate value */ 


#define \WucOflBPropChaia 


0K08OOU 


/• 


— > dynamic vahie off prop chain •/ 


#defin0 VatueDynamic 


QxlOOCfU 


/• 


=> dynamic value */ 


#define VtdueUodeletable 


QK2000U 


/• 


can't be deleted */ 


#define VahieProtected 


Ox4000U 


/« 


=> locked/protected value ♦/ 


tfdefineA^OueDcfiDed 


Q18OOOU 


/• 


=> fiilly defined (in read only) */ 



/• VahieUndcleteablc and VahJcProtected are levels of protection bits. •/ 
f* In Older to make dealing with dynamic values easier, the following macros are provided. 
IsDynamicValue(v) is a more self-documented test to see if a TOCValueHdr is indeed a 
dynamic value, while DYNE?nENSIONS(v) allows simpler notational access to a dynamic value 
header's extension fields. 

#define IsDynamicmcCv) ({(cr0CVahieHdtf»tr)(v))->vahMFlags & VyucDynamic) != 0) 
tfdcfine DYNEXIENSIONS{V) /* to make access to wrrmsinns a "fitUe" casier*\ 

((C^OCWueHd^Plr)(v)>.>dyn^WueData.extensions) 
/* The dynamic value vectors are defined as follows •/ 
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struct pj^amkyducVcctoffintries { /* Layout of a dynamic value vector entiy: */ 
CMHandlfirAddr handler, /• the handler address •/ 

CMVahie (hisValue; /♦ the handler's value (C++ "thiO 

Boolean active; /* true => >lgTv^]*r is in callii^ chain */ 

}; 

Q^pedef struct DynanucVahieVectosEntries Dynamic'V^ueVectoiEatnes, 

•DyoattticVahrVectoiEntrtesPr. 
struct PyQamic\%iueVcctQr { 

DyIlaxDic^^ueVectQ^tIies cmC3etValueSi£e; 

DynasmcValueVectoiEntries cmRcadValueData; 

DynanicValueVectoiEDtrks cmWriteVahieData; 

DynanucyalueVcctoiEntries cmDoseitValueData; 

DynamicValueVectotEDtries cmDeteteValueData; 

DynanucValueVecto^Dtries cmGetValuelhfo; 

DyaamicValueVectotEntries cmSetVahieType; 

PynamtcWueVectodSntries cmSetVahieGen; 

DynanacValueVectotEntries cmReleaseVahie; 

>; 

typedef struct DyoamicVdueVcctor DynamicValueVector, 



When a handler is called^ it is e:q>ected to do its operations 
on the "base value" of the value passed to it. It gets its base 
value using CMGetBascValuc (). However, wc don't want to 
allow recursive use of the API for the same value. That 
would call the handler again and we would be in an infinite 
loop. Thus the active switdi is provided to check for this so 
we can icpoti an error. 

The dynamic value vector is initialized with each handler 
address thisValue set to NULL, On first use we use the 
ZQctahandler which was returned from the "use value" 
handler (the metahandler address is saved in the value 
header extensions) to get the proper value handler address. 
It is saved in the handler field of the vector entry. Remember 
we may have to search up through a dynamic value chain to 
find an 'inherited" value handler operation. Thus the handler 
used may correspond to a difierent dynamic value. We must 
therefore save the dynamic value refNum along with the 
handler address (in the thisValue). It is similar to the C++ 
**this" pointer for the value handler operation). 



own dynamic value header. At the other extreme no handlers 
are supplied for the operation and we end up using the **real** 
value &at spawned the dynamic value(s). In that case the 

2^ handler pointer in the vector entry remains NULL and the 
thisValue will be the **real" value refNum. With no handler 
we use the actual API routine to process the real value. 
As with standard handlers, to sin^lify this descr^tion, 

30 some macros are defined for calling the dynamic value 
handlers. These macros will require Ae following typedcfs 
as casts to convert the generic handler typedef, HandlerAddr 
(the type used to store the addresses in the vector), to the 
actual function type: 
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CMSize (*TfcmGetVal«SizeXCMValue vahie); 

typedef CMSize (HfeniReadVaueDataXCMVahae value, CMPtr buffeii CMCount offeet, CMSize 
maxSize); 

typedef void (*TcmWriteWueDataXCMValiie value, CMPtr buflfcr, CMCount offset, CMSize 
size); 

typedef void (*TcmIn3eitVaiueDataXCMValue value, CMPtr buffer, CMCount ofEsct, CMSize 
size); 

typedef void (*TcmDclcteValueData)(CMVihie value, CMCount offset, CMSize sire); 
typedef void (*Tcn^3ct>^hjeiInfoXCM%lue value, CMConiaincr ♦container, CMObject ♦oltject, 

CMPtppcrty ♦prupeity, CMType ♦type, CMCfcnciatioQ ♦gcncratioa); 
typedef void (♦IfcmSetValucTypeKCMValue valiK, CMiype type); 
tj^iedef void (*TtinSelVahieGen)(CMValt»e value, CMGcMration generation); 
typedef void (•TfcmRcIcaseVah«!)(CM%lue); 



55 

Of course, in the siii^)lest case, where the handler is Here now are the maaos used to do the calls using the 
provided for the original value, the thisValue will point to its vector. 



© 1992 ^iple Computer, Inc. 



#de&ie CMDynGet\^iieSize(v) 

(*CIbinaetVaIueSizepYNEJaENSIONS(v>.>dynValueVcctor.cnjOet\MueSizcJ^ 
#definc CMDynReadVahieData(v, b, x, m) 
(*CItinR«ad\^ueData)DWEXIENSIONS(v).><|ynVi^ 
CCMPtrXb), (CMCouDt)(x), (CMSize)(m)) 
#define CMDynWteVih»Data(v, b, x, n) 
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(*CIlOTWrite%dueDatapYNEXlENSIONSCv>>dyii\WueVoc^^ 

X (CMPtr)(b), (CMCouatXx), (CMSizcXn)) 

#define CMI^mInsezt^^hicDate(v, b, n) 

(*CIlMiInscrtVahjd>atopTNBXlENSIONS(v>>dyn 

(vX (CMPtr)(bX (CMCouiit)(x), (CMSizcXn)) 

#define CMI>3mI>eleteWueData(v, a) 

(*(lbinIklcteVaucI)ata)DYNEXIENSIONS(vV>dyn\^ 

(vX (CMCountXxX (CMSize)(n)) 

#dcfinc CMI>yiGetWiieIiifb(v,c^j,p,t, g) 

(•(lbinGctVyucInfo)DYNEXIENSIONS(y)->dynValwVccto 

(CMContaincr*)(cX (CaHOl)iect*)(obriX (CMPropcrty*)CpX (CMiype*XO» (CMC3eneration*Xg)) 
^define CMI>}niSet\^TypeOr, t) 

(♦CItiiiSctValucTypcpYNEXIENSIONS(v)->djmValueVcct^^^ 
(CMiype)(t)) 

ttflefine CMDyxiSct%lueGen{v, g) 

(•CEmiSetValti(<fen)iyyNEXTENSIONS(v>odyDValmV(^^ 

(CMGaieration)(g)) 

#define CMDyiiReleaseWue(v) 



As mentioned earlier, each corresponding API value 
cperation must check to see if it has a dynamic value and call 
the corresponding handler which does the operation. It must 
get the proper address on first use. It must set switches to 25 
mark the handler as active. It must also set a switch to allow 
CMGctBascValue Q calls which are only allowed from 
dynamic value handlers. Thus the algorithm for calling a 
ydlac handler looks something like this (ignoring all errors 
for the moment): 



© 1992 Apple Coxoputer, ioc. 

if (IsPynaxnicValue(v)) { 

V = GetDynHfflKilerAddress(v, h, g); ,5 
if (IfiDyiiaiiiicAfelue(v)) { 

StgDaII>y]iHattdleiInUse(v, h); 
AlbwCMGetBascWueCamtaiiKrX 

Call the proper dynamic value bandJa with one of the 
above macios defioitioas. The macro will pass the 
appropriate value coxrespandiag to a possibly inherited 
handler. If the handler returns a value save it to be ^ 
returned as the result 
DisAUowCMGetBaseralueCcQntamer); 
SignatDyiiHazidleiAvulableCv, h); 
return [result]; 

} 

} 45 



In the above algorithm, v is a dynamic CMValue (note 
that GetDynHandlerAddress may CHANGE it); h is a 



This is the value returned and whose we set. We do the call 
and reset the switches, all using the same **tfais'* value. 

Note, in the limits the search for the inherited handler may 
end up finding the original **real" value that spawned the 
dynamic values. Thus what is returned from 
GetDynHandlerAddressO in this case is a **real'' value to be 
operated upon using the standard API routine itself. That is 
why a second IsDynamicValueQ must be done to bypass the 
handler call and switdi setting^esetting. Since there is no 
guarantee the value coming back from the 
GetDynHandlerAddressO call is the one that went in, the 
code must reload any copies of the value sometime follow- 
ing the GetDynHandlerAddressO calls, 

The following macros are defined. Hicy basically mimic 
the above algorithm, but here take errors into account 
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ffdefine Gct pyn H a n d l erArt d r essCv, h, g, s, x) if ((v = cinGetPynHnidleiAddress((CMVahjeXvX 

&DTfNEXlENSIONS(v).>dynValucyectorJi, (CMGlobalName)(g), s)) = NULL) \ return x 
Idefiue SignalDynHandlcrlnUseCv, h) DYNEXIENSIONS(v>>dynVfllucVectDTJi.active ~ tiuc 
#dcfine SignaIDynHandIerAvailable(v, h) DyNEJCIENSIONS(v>>dynWueVectarJi.active = &Ise 
#define AllowCMGetBaseVaIuc(coatainer) ++((CcDtaine*tr)(comainer))->getBaseValueOfc 
#define DisAlbwCMGetBaseVahic(conlaiiier) if ( — ((Containeri>tr)(coiitaiDer))->getBaseValueOk 
< 0) ((Contaiii«PtrXcontaioer)>>gctBaseValueOk = 0; 



pointer to a vector entry in the extensions; and g is the 
mctahandlers operation type string. 

The GetDynHandlerAddressO routine takes a vector entry 
and sets the handler address as a function of the "g" 
metahandler operation code. On first call it will search for 
inherited method if necessary. The vector is updated with the 
found handler address and the associated **this" value saved. 



The IsDynamicValueO call is defined above. The '*h" in 
all these macros is the vector entry name, and the '"x** 
parameter in GetDynHandlerAddress is used for error 
reporting. Also for GetDynHandlerAddress, the "s" is the 
name of the API routine doing the call. This is used by 
cmGetDynHandlcrAddrcssO wsply as an insert if it should 
report an error prior to returning NULL. 
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Note tbe AUowCMGetBaseValue and DisAliowCMGet- There are three varieties of metahandlers: session, 

Base Value macros. As mentioned earlier, a container, and value, though this is not a fundamental 

CMGctBaseValueO is only allowed from value operation distinction. Only value metahandlers are inqwrtant to the 

handlers. The two macros control a single switch, present invention. 
gctBaseValueOt which the CMGctBaseValueO routine 5 

diecks. The switch is actually a counter which* just to be ^— 

safe, is never allowed to stay negative. 0 means CMHandkiAddr CMGetMctaHazxller(oonst CtoSesnoQ sesskmData. 

CMGctBaseValueO is illegal Greata: than 0, it's legal. The const CMGbbalName typeName) 

reason the switch is a counter is because dynamic values use — — ^— i^^— — ^— 

CMGctBaseValueO to do Iheir operations in terms of their This function searches the metaHandlcr symbol taWe 404 

base values. If a dynamic value's base is also dynamic (i.c., for the specified typeName and returns die associated metah- 

we have layered dynamic values), then we have a nesting andlcr address. If no metahandler is associated with that type 

condition. Hence the counter. name, it returns NULL. 
C, Routines 

The Application Program Interface includes a number of 

calls to Container Manager routines to perform session i^ CMHandkiAddr CMGetOpenLtiaa(c%nype taisen^, ooost 

operations ; container operations, type and property CMdobalNaine operationl^); 

operations, object operations, value operations and reference — — — — — — — ^-^—^^^^^ 

operations. Only of the calls which are inj^rtentfcr ^^^^ ^ targeflVpe which has a globally 

an understanding of the invenUon will be descnbed herein. ^^^^^ that name to find a metahaidler. It 

i. session uperauons 20 then calls the metahandler to get the handler routine address 

for the specified operationiype. The function returns the 

CMHandkrAddr CMSetMetaHaodler(cocst CMScssion scssiooData, resulting a(WresS. , ^ . 

const CMGiobalNametypcxutiM,CMMetaHaiKiicrinetaH^ MetahanolcT proc addresses are givcn to the Container 

Manager by caUs to CMSeiMetaHandler. The global name 

^. ^. , , ^ ^ ,^ 25 for the input targcfiype is treated as the typeName to find the 

This routme records the association of Global Names with metahandler. 

their metahandlers in metahandler table 404 (FIG. 4). The 2 Object Operations 

designated metahandler will be associated with the type- * v-^p^a 

Name. The previous metahandler for this type name, if any, 

is returned. If there was no previous metahandler defined, 3Q cMObject CMNewObject(CMContamer taigetcontamer); 

NULL is returned. The association between handlers and — — *— — — 



type names is global within a session, rather than specific to 

a given container. A refoum to a new object in the designated container is 

A metahandler wiU be called whenever the Container returned. At this point the object has nothing but an identity. 
Manager or the plication needs to find out how to perform 

a given operation on a container or value of this type. The — 

metahandler can define specific handlers for any number of c^Objcct CMC3ctNcitObject(C\fCoiiuincr t«xetContainer. 

different operations, potentially with completely different CMObject currObjcct); ^ 

interfaces. Metahandlers for viues are required to support 

certain value operations, listed previously. A rcfnum for the next object defined in the same container 

Whencalled, a metahandler returns a procedure pointer to 40 is returned. curcObject is generally a rcfNumprcviously 
specific handlers that can carry out the desired operation. returned from this routine. Successive calls to this routine 
TVpicafiy, these procedure pointers will be cached and then wiU thus yield all the objects in the container, 
used in the ncnmal manner. Each metahandler may provide Objects are returned in order of inaeasing ID. If there are 
handlers for imy number of qperations, though it itsetf no larger object IDs defined, NULL is returned. To begin the 
implements o^y the operation f obtammg and returning a 43 iteration, pass NULL as the object refnum. 
S^"oS2 ^ metahandler has the f oUowmg ^ ^^^^ desci£ons are objects, they wiU 

*^ be returned in sequence as they are encountered. Only 

objects in the current container will be returned, not objects 

Ca^lProcPtr CMMetaHaDdkr(CMiype taigcflVpe, ^ ^^^^ Containers, 

const CMGlobalName operatiaaType); ^ 



_.. . , . ^ CMProperty CMGetNextOlgcctP»pcrty(CMObject (htObjcct, 

This is the required prototype of any metahandler regis- CMProperty cunPtopeity); 

tered by the plication using CMSctHandlaO' When a — ------- 

specific operation is required, the metahandler is called, and 

it must retum a CMProcPtr for the opaation, or return ^ r^um for the next property defined for this object is 

NULL to indicate that the operation is not available. Once retunied. cunrftroperty is generaUy a refNum previously 

retrieved, the CMftocPtrs may be cadied indefinitely. returned from this routine. Successive calls to this routine 

targetrype is the rcfnum of the type to which the opera- ^ ^s yield all the properties fcr the given object, 

tion will be applied, and operationiype is the name of the routine returns the refNum for the next property 

desired operation, targctiype is required because in some ^ defined for the given object ff there are no more properties 

cases the operation may be applied to values whose type has defined for this object, NULL is returned, ff currPropcrty is 

no global unique name. NULL, the refNum for the first prq>crty for the object is 

This approach frovides more flexibility than simply pass- returned, 

ing a vector of procPtrs, and allows eadi operation to have CMGlobalName CMGetGlobalName(CMObject 

its own prototype for static type checking, which would be 65 theObject); 

impossible if operations were indicated by passing a selec- The name of the designated object is returned. This 

operation is typically used on types and properties, but it can 
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be applied to any object with a Globally Unique Name 
property. NULL is returned if the object does not have a 
GlobaUy Unique Name. 

3. Type and Property Qperatians 

All types and properties must be registered before they 
can be used. The operations behave the same on standard 
types and properties as on nonnal types and properties. 
However, standard types and prqpeitLes will not actually be 
given TOC entries for their descriptions just because they 
are registered. If additional, non-standard properties are 
added to the description of a standard type or property, they 
will be stored. 

The refhum returned from registration can be used in 
exactly the same manner as an object refhum in the object 
and value operations. 

Types and properties may be registered more than once; 
the refhum returned from all the different registrations of the 
same type is the same. Identity of types is defined by string 
equali^ of their names. 



40 



C\ffIVpe 



CMRe£istetiype(CMCaataiDer taisetCantainer, 
const <2MGIobalNaiiie name); 



previously returned from this routine. Successive calls to 
this routine will dius yield all the property descriptions in die 
container. 

I^opcrties arc returned in order of increasing ID. If there 
^ are no larger property IDs registered, NULL is returned. To 
begin the iteration, pass NULL as the property refaum. 

CMComt CMAdSaselVpeCCKn^ type, CMiype basel^pe); 
10 

This routine defines base types for a given type so that 
layered dynamic values can be created. Base types essen- 
tially provide type inheritance. As previously described, the 
15 type trees created by CMAddBaseType() are stored in **type 
objects**. 

A base type is added to the specified type. For each call 
to CMAddBaseTypeQ for the type a new base type is 
recorded. They are recorded in the order of the calls. The 
20 total number of base types recorded for the type is returned. 
In the embodiment described herein, it is an error to &Xtssnpi 
to add tbG same base type more than once to the type. 



25 CMCount CMRemoveBasel>pe(CMlVpe type, CMTypc base'fypc); 



The designated type is registered in the designated 
container, and a refnum for it is returned. If a type with tiiat 
name already exists, the re&fmn for it is returned. Standard 
types may be registered, but this is not required. 



CMProperty CMRegi5teiPioperty(CMCoxitaiaer tai^etOontainer, 
const CMGlobalName name); 



The designated property is registered in the designated 
container, and a refiium for it is returned. If a property with 
that name already exists, the refNum for it is returned 
Standard properties may be registered, but this is not 
required. 



CMBoolean CMI^type(CMObject tfaeObject); 
CMBooIcan CMIsPtopcity(C[MObject thcObjcct); 



These operations test the designated object and return 
non-zero if it is a type description or a property descrq}tion, 
respectively, otherwise 0. 



CMIVpe CMGetNextiypeCCMContaiiier taisetContainer, 
CMiypc cuniype); 



A refhum for the next type registered in the same con- 
tainer is returned. cuirTypc is generally a rcfNun^ircviously 
returned from this routine. Successive calls to this routine 
will thus yield all the type descriptions in the container. 

Types are returned in order of increasing ID. If there are 
no larger type IDs registered, NULL is returned. To begin 
the iteration, pass NULL as the type refhum. 



CMPtopctty CMGctNextPrc3pcrty(CMCoiilaincr targetContainer. 
CMftopcrty cunPropcrty); 



A refnum for the next property registered in the same 
container is returned. curtProperty is generally a refNum- 



The specified base type previously added to the specified 
type by CMAddBaseTypeQ is removed. If NULL is speci- 
fied as the baseType, all base types are removed. The 
number of base types remaining for the type is returned. 

4. Value Operations 

All the I/O calls in the present embodiment do 1/0 to or 
from a buffer provided by the application. 



CMValue CMUseVahio(CMObject object, CMPrcperty property, 
CMiypctype); 



40 This routine is used to get the refNum for the value of an 
object's property of the given type. NULL is returned if the 
value does not exist, or if or the object does not contain the 
prapeity. Jf the type of the value corresponds to a global type 
name that has an associated *\ise value*" handler, or if its 

45 base types (if any) have associated **use value** handlers, a 
dynamic value will be created and the refnnm returned will 
refer to a dynamic value rather than the base value. 
(Normally, an application will never be aware of this 
difference.) 

so Note, if the value is used as an embedded container, then 
that embedded container must be opened and read using 
CMOpenContainerO* The data, i.e, the embedded container 
for such a value can only be defined by using 
CMOpcnNewContainerO. The container type name must be 

55 associated with a special set of handlers that define a '^return 
parent value** handler. This handler returns the parent value 
refNum whose data contains the embedded container. 

There is no restriction on reading the data for an embed- 
ded container like any other value data using 

^ CMReadValueData(). However, the data for an embedded 
container value includes a TOC. Unless a "blind" copy is 
being done, the TOC read this way is of not very much use. 

The following C-languagc code implements the 
CMUseValueO routine. 



30 
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CMV^ C\t_PIXEDAIlGS CMUscVilue(CMObjoct object, CMProperty property, Cmype type) 

TOCPiopertyPtr thcProperty; 
TOCVilueHdrPtr tbe\yueHdr, base\yusHdr, 

ContaineiPtr contaioer, 
ExilI£BadObject(object, NULL); /• validate object */ 

Esifl£BadPiDpcrty(propcity, NULL); /* validate property •/ 
Exitlffiadriype(typc, NULL); /* validate type */ 

container c ((TOCObjectPtr)objcct)->containcr, 
if (cQntaixKr>>tt];getCoiitainer 1 = 

((TOCObjcctPtr)piDpcity)->container-->targctCo!itaiMr {i 

coiitaincT->targctCaiitairier ! = 

(CroCObjectPtr)type)->contaiiw->taigctContaiMT) { 

ERROR3(CNLjit_3CoiitaiiKrs, CONtAINERNAMEx(contaiQer), 
CONTAINERNAMEx(((rCX:ObjectPtr)pn5perty)->container), 
CONXMNEIWAl^((CroCOb)ectPtr)type)ocxmtaaw)); 

return (NULL); 

} 

/♦ Find the TOCProperty belongiug to the object with the property ID of the 
specified p i up eit y object */ 

theProperty = cixiGetOb>ectPropcrty((TCX:ObjectPtr)object, 

((TOCObjectPtr)piDpeity>>obicctID); 
if (theProperty = NULL) /» if property not in object... •/ 

return (NULL); /♦ ..tdl user about it •/ 

/♦ If the resultmg value is a dtynamic value, just return it. If it isn% this 
misht be the first use of the value. Id that case we must check to see if a 
dynamic value must be created. This is done by calling cmPonowBaseiypesO to do 
a deptb-first search starting fiom the grven type oa all of that type's base 
types. Dynamic values are created for each type that has a "use value" handler 
(**new value" handlers are only required for CMNew'%lueO). Hm resulting dynamic 
value is tetomed or the ^'real** valtie if there an no cfynamic vahies. */ 
theVahjcHdr = Cn)CVihieHdrPtr)cmGetPiopeTtyType(thePiDperty, 

((T0C0bjectPtr)type>o6bjectID); 
if (the\^ueHdr) { /* if we have a valie header... */ 

if (theVUueHdr->dynVahieData.dynValuc 1= NULL){ /* -of dynamic value 
exists... ♦/ 

thcMdueHdr = tbeValueHd>>dynValucData.dynVahje; /♦ ... just lee it, 
but.. */ 

-HHhe>^ilueHdr->useCoizit; /* „ixrunt dynamic value uses*/ 
} else { /* ...if no dynamic: value yet.. ♦/ 
baseWueHdr = tbeValueHdr. 

theValueHdr = ciiiFollowTypes(theVahKHdr, (TDCObjectPtr)type, false, 
NULL); 

-hfbase WueHdr->useCouni; f* ii^r use count on base value */ 

} 

> 

return ((CM\felue)fiicValueHdr); J* return real or dynamic value */ 



The cmFollowTypes 0 routine r^erred to in the above 
code creates dynamic value layers for the passed type and all 
of its base types, if any of these types have a **use value" 
handler. This routine is only called by CMNewValue () or 
CMUseValue 0- For CMNewValue •"metadata" handier 
and "new value** handlers arc also required. The top-most 
dynamic value header pointer is returned, and is in turn 
returned from CMUseValue () or CMNewValue (). NULL is 
returned if an error is reported. The original **rci** value is 
returned if no dynamic values are created. For CMUseValue 
0. the isNewValuc parameter should be set to false. It should 
only be set to true for CMNewValue (). Also for 
CMNewValue 0. the constructorData must point at the 
CMNewValueO . . *' parameters. These are consumed as 
the base type metadata (returned from the **metadata'* 
handler) describes how to create data packets from the . 
. " parameters. The packets, in turn, are passed to the ^'new 
value" handlers. A "new value" handler uses its data packet 
to write (possibly different) data to its base value. This 
written data will then be read and used by the **use value" 
handier. 

The "use value" handler is called for both the 
CMUseValueO and CMNcwValucQ cases*. If it*s compan- 



45 ion "new value" handler wrote data to its base value, the 
•*use value" handler will probably read the data to aeate its 
refCon. The rcfCon will be passed to all value handlers. The 
*^ise value" handler returns its refCon along with another 
metahandler address that is used to get the value handler 

50 addresses. These are then used to create the dynamic value. 
To produce all the required dynamic values, 
cmFollowiypesO recursively follows the types, looking for 
base types as defined by CMAddBastfl^Q- Each type can 
have any number of base types. The recursion effectively 

55 produces a depth-first search of all the base types. 

As each type is completed (i.e., no more base types for it), 
a dynamic value is aeated as described above. That is, for 
CMNewValueO, a typc*s **metadata" handler instructs us on 
how many CMNewValueQ . . " paramett^ to consume 

60 and how to construct their packet That is passed to die "new 
value** handler so it can write some appropriate data to the 
base value. The *\jse value" is caEed in all cases which reads 
the data written by **new value" to construct its rcfCon. The 
refCon is returned here along wifli the metahandler address 

65 that will yield the value handler routine addresses. 

The refCon and metahandler address arc passed to 
newDynamicValue() to construct one dynamic value (layer). 
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The resulting dynaioic value is used as the base value for the 
next layer. This produces the desired data structures. 

Note* because this routine searches through the types 
down to their leaves, and then generates the dynamic values 
on the way back **ap", the CMNewValue () . . " parameters 
must be ordered for the "deepest** type first For exan^e, 
given a type tree in which Tl has base types T2 andT3, and 



44 



T3 has base types T4 and T5 (read as Tl inherits from T2 
and T3, and T3 inherits from T4 and T5, tiie depth-first 
search, starting atTL yields the sequence: T2 T4T5 T3 Tl. 
Then this is the order the CMNewValueO parameters 
5 must be in. 

The following C*language code implements 
cmFolIo\naVpesO: 



@ 1992 Apple Conner, Idc. 



TOCVOueHdcPd cniFoUowiypesCrOCVahieHdrPir baseVahieHdr, TOCOlqcctPtr type, 
Boolean uNewWue, vOist "constnictorData) 

{ 

ContaincrPtr container = baseVahieHdr->contamerr 

TOCObjcctPtr basely 
TOCPropcrtyPtr baseTjiePropcrty; 
TOCV^ieHdiPtr ^V^taeHdr, base^^tufiRdiO; 
TOCWuePtr Ihc^luc; 

CMHaodlerAddr vseValueflasdler, iKwYalueHflndler, netaDataHandleT; 
unsigned char *dataPack£t; 

char *aewOrUseVahicNaine, •metaData, *typeName; 

CHRefiCoD ie£Caa; 
CMMetaHandler metaHandlen 
CHBoolean success; 

/* If any enon are reported, and tl» eixor handler xetutns, we NULL out die base */ 
/* value. Tliat essentialy **put8 the breaks" on the dynamic votue generation. Hw */ 
/• NULL result will work ist way back to CarfNewVahaeO or CMUse\WucO which it will */ 
/* return. •/ 
/* Note, as soon as we detect an error in here, we tec all the dynamic values we */ 
/* created for the **rear value. That shoiild put things back the way they were */ 
/* originally. Of course, error reporters are not suppxc to return. We*xe being *f 
I* *'kind*' here just in case they do. 
if (baseVahicHdr = NULL) return (NUU.); 

bascValucHdiO = baseValucHdr. save current baseValueHdr fiar errors */ 

/* U the current type has any base types, caUcmFbUowiypesC) recursively 6>re^ */ 
/* of tiiose base types. That brings us back to here where we will check each of */ 
/* those base Qrpes for base types of their own. Ihis process continues down to the */ 
/• "Tsottom", Le., leaf types, where we bypass this jaece of code. The types ate then V 
t* processed as Ote recursion unwmds. It is this code, dien the effects the depth- */ 
/* first proces^Qg of ttie base types. «/ 
basel^peProperty = cmGctObjectPropertyCtype, CM-_StdObjID_3aseTypes); 
if (baseTVpePropetty 1= NULL) { t* process this type's base types */ 
the ValuoHdr - CnX2VahieHdiPtr>nnGetListHi»d(&basel>pePioperty-^^^ 
if (tbeVahieHdr t»NULL){ /* double check for value lx3r «/ 
tbeValue « C^OCVahiePtr)cmGetListHead(&tfaeValueHdr->vBlueLtst); /* 1st base ID 
while (IheVahje 1= NULL) { 

baxiype =1 cniFmdObject(containcr->toc, theVUue->valiie.imni.uloagVa]ue); 
if (basetype) { 

baseA^IucHdr = cinFoUowiypes(baseVah]eHdr, basetype, isNewVahie, 

constructoiData); 
if (baseWucHdr = NULL) return (NULL); 

} 

theV^ue = (10CYihiePtr)cmGetNexlListCeIIClfaeVahie); /* look at base type V 
} /♦ while ♦/ 
} /• theValueHdr */ 
} /♦ basciypePioperty */ 

/* We are now at a type whichhas either has no base types or that had all of its base */ 
/* types processed (again through here). This is where we (fetetmine whether the type */ 
/* will spawn a dynamic value. We caU basUseWueHandler() that checks for ^ «/ 
f* the **use value" handler for the type. It also checks for the **nietadata" aul '*new */ 
/* value" handleis if we were originatly called fiom CMNewValueQ. If tt doesn't pass */ 
/* the tests we return the original base value unehflng ^, if it does pass Hbc tests, */ 
/* we create a new dynamic value (layer). */ 
/* As descibed in (be documentatioQ at front of diis file, we call the **metadata** and */ 
/* **new value** handleis first only for CMNcwWueQ. Vot CMNew\yueO or CMUseVahicQ */ 
/* we then caU the *use value handler. For ^ **ww vahie" call we must first build *{ 
i* the data packet from the CMNewVahie() parameters the metadata returned */ 
/* &um the "metadata" handlet Ihc packet is seat to the **oew valuei^ haulier. There */ 
/* it can use CMScanDataPacketO to extract the packet back into variables. */ 
/* Note, as the packets far the layers are created, the constnictorData parameter */ 
t* pointer marches across the CMNewVahieO paraneters. Siwe we are buMng */ 
i* the layers as we move iq> the inheritaoce hierarchy, from bottom to top, that is *l 
t* what detemunes the parameter specifications discussed above. Fiutfaer, it is also *f 
t* why the constructorDaia is a va^Jist*. The hlgter layers must kix>w what the •/ 
f* current parameter pointer is. If we had built the hierarchy from top to bottom we */ 
t* wouldn't have needed die ♦/ 
t* And speaking of layers — the newDynatnicVdueO ^ ^ xcspoosible for */ 
t* creatmg a layer. It builds upon the current baseValueHdr and returns a new one. */ 
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/* tbey arc passed up the lecursiYe calls as the fiioctkni result to build tie layer V 
/* chain. The final, top-most layer, is the one evcnnially returned to CMNewVahicO */ 
f* or CMUseValtieOt who then returns it to tl^ user. */ 
UMVilufHandler = hasUseVaIueflandkr(base^^h]eHdr, type, isNewVahie ? 

&newVahieHandler : NULL, ftmetaDataHandter); 
if (ISessioDSixxess) return (NULL); 

if (useV^ueHandler) { /* if dynamic value layer is to be created*/ 
if CisNewWue) { /• extra stuff for CMNcwVahieO." */ 

/* Here we*ro doing a CMNcwVahicO - call the "Inetadata" handler to get this */ 
/* type's metadata. We can then use that to build a data packet */ 
metadata = (*(char •(*)(CNnirpc))mctaDataHandlar)((CMiype)type); 
dataPacket = createDataPacket(typc,inetaData,cQDstn)ctDrData); /*cieate data pkt,. */ 
if (IScsskHiSuccess) { /♦ ..af it fiuled... •/ 

cniI>ekteAin)ynamicValucLayers(baseVJucHdi04sNcwValue);/* ...delete all layers •/ 
retum CNUUL); /♦ ...abort creation ♦/ 

} 

/* Call the valiK" bandlei: It should use the data padcet to write data to */ 
/* its base vahie. */ 

success = (*(CMBoolean (•)(CMWue, CMiype, CMDataPacket))newValueHandlcr) 
((CMVahie)baseValue}Ur, (C!iiype)type, (CMDataPacket)dataPacket>; 
if (dataPacket \= NULL) CMfr«e(dataPackeC); /* free the packet */ 
newOrUse'VWueNamD = "CMNew^ue'*; 
} elsc{ 

ncwOrUse^iucNanie = **CMUscValuer; 
success = tnic; 

} 

/* In all cases we call the '^ise value" handle; It sboukl read the data written by *i 
/* the vatoe"* handler to create its refCon. ll letums tie refCoo and a */ 
/* CKtbandler pointer that we will use to get the value operation handler addresses. */ 
/* This is then passed to newDynamicValueO to build the new dynamic vahK (layer). */ 
if (success) { 

mftaHanriVtr = NULL; /* **use value" must set this or enor */ 
success = (•(CMBoolean (•XCM%lue, CMiype, CMMetaHandlcr*, 
CmefCon*))useVahieHandlerX(CMVahie)baseVahKHdr, (CMiypc)type, 
AmetaHandler, &iefiCoa); 

if (success) { 

if (metaHandler —NULL) { /* we must get a methandler back! */ 
typeNamc = cmIsGbbaINamcObiect(type, CM_StdObjn>_GlobanypeNanic); 
ERROR2(CM_ctr_NoI>ynMetahandkr, typeNan^, C0N1A3NERNAME); 
success = fabc; 

} else 

basrValucHdr = ncwDynamic Value (base VahjcHdr, type, metaHandlcr, 
icfCon. newOrVseValueName); 

} 

} 

if (Isuccess u baseVahieHdr — NUIL) { /* if something went wrong... */ 

cmI}ekteAin>ynainicWueiLayers(faaseValu£Hdr(), isNewWue); f* ...free the layers */ 
baseValucHdr = NULL; /• tfas win abort the recursion •/ 

} 

} 

retum (baseValueHdr); /* return dynamic value la^er */ 



The ncwDynamicVaiue routine referred to above is called 
only by cmFoIIov/iypes() to do the actual constiucdon of 
the dynamic value for the spedQed base value. The type is 
the type that is causing this dynamic value to be created If 
the base value is a "real" value, then the dynamic value is 
added to a "dynamic values" property for the object who 
owns the value. The •^dynamic value"s property is created 
for the first dynamic value for that object All further 
dynamic values wi& 'Yeal** value bases are simply added as 
values (headers) to that property. If the base value is itself a 
dynamic value, then the newly created dynamic value is 



chained to the base (dynamic) value. It is only a backward 
link from the new dynamic value. 

The pointer to the new dynamic value is returned. NULL 
is returned if any errors arc reported. Note, the 
newOrUseValueName parameter is the string 
"CMNewValue'* or '*CMUseValue*' and only used for some 
of &e error inserts. 

By passing the returned dynamic value pointer as the base 
value to succeeding new£^namicValue() calls, layers of 
dynamic values are constiucted. 

The following C-language code implements 
newDynamicValue(). 



@ 1992 .^iple CQnq}Utei, loc. 



static TOCValueHdiPtr CM_NEAR newDynamicValue(IOCVahKHdiPtr baseValiKHdi; 

TOCObjcctPtr type, CMMctaHaailcr metaHaaner, CMRcfCon rcfCon, 
char •newOrUseVahicName) 

{ 
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CoDtaineiPtr conbuner = ba$cVah]eHdr->coatainer 

TOCObjcctPtr thcObject; 

TOCWhieHdPtr tfaeDymmicVahicMdr, tiieRealValueHdr, 



DynValueHdiExtPtr 
Boolean firsfDysamicValiie; 
char *typeName; 

if {metaHandler ~ NULL) { /* we mv^ have a metabandler! */ 
typcNamc » cmIisGlobaINaiDcObjcct(typc CM-_StdObiID_QlobanVpcNanc); 
ERROR2(CH_err_J^oMctahandlcr, typcNamc, CONIAINERNAME); 
«tum(NULL); 

} 

/* It is an enor for laycied dynamic values to pass as the base vahie any oHkt */ 

/* value faeadcT other than the most lecent. the ccxfe near the end of this routine */ 

/* chains layered dynamic values together with each value pointing back to its base. */ 

/* The original *'xeal" value gets a pointer to the last one (in the dynValue union */ 

/* field of the value header). So by seaichiag back up the r b aj n to the "real" vahie */ 

/* we can get at ttiis pointer to see if the base value passed is equal to it and */ 

/* repoTt an error if it is not Of comse, the first time the "ceaT* value is passed */ 

/« and the dynValue will be NULL. So we will know this case too. «/ 

theRealWucHdr = baseVahieHdr, /* start with the canent base •/ 

while (IsDynamicWue(theRea]VihuHdr)) /* loop back till we find 1st vali^ */ 

theRealValueHdr = DYNBXlENSIONS(theReatN^ueHdr)->base\^;/*that not dynamic value */ 
firstDynamicValue = (Boolean)(theReaIVah^eHa^>dya^%hJe^)ata^yn\fahlc = NULL); 

if (t fiisfDynamicValue && /* do the base check.. «/ 
theRear\^Hdr->dynValucData.dynValue l== baseVahicHdr) { 

ERR0R2(CM_crr JadRcalVahie, newOrUscVahicNamc, CONIAINERNAME); /♦ ..^ps! */ 

ictum(NULL); 

} 

/* Create the dynamic value, i.c., a value (beaikx) that is belongs to a special V 

/* property of the caller's obtject that owns the base value. The d^ect "owningT the •/ 

/* dynamic value is flagged to incUcate tiiere are dynamic vahKS present in that */ 

/* ot^ect. Ihis protects it fiom piemature deletion. The fiag is cleared wlun tl^ «/ 

/* last dynamic value fior for the object is released We don't use the '^protected" «/ 

/• flag, which is used for similar purposes, just to be geoeral. Maybe we could */ 

/* someday have a protected object with dynamic vahiesl */ 

/* Note, the type we give the dynamic value is that of the type that caused this «/ 

/* dynamic value to be generated. We never use that feet But we got to give it V 

/* something and it could aid in debugging dils turkey! Do you reotly ihink I am V 

/* going to get all this die first time? Want to boy a bridge? */ 
theObject = cmDefineObjcct(container, baseValueHdr->lhePioperty->tI»Object->ol^tID, 
CM_StdObin)_J)ynamicValuc3, 

0, /* 0 stops dup checks, was **type->objectID" */ 
NULL, container->generation, kCMDyn'lWuc, 
ObjcctObjcct, &thePynamic%hieHdr); 
if (theObject — NULL) return (NULL); 

thcDynamicValucHdr->typcID = typc->objectn); /• give the type ID sonKthing valid */ 

theObject->objcctFl^ 1= DynamicVSOufisObject; /♦ make sure object is flagged •/ 

/* The dynVilueData field in the value header is a union. wiUi two alternatives. */ 

/* **dyn^ue'* alternative is a pointer fiom the base value heacfer to its dynamic •/ 

/* value. The "extensiansT' alternative is for &e dynamic vahu header itself and «/ 

/* pohits to the additional information, Le., extensions, neetfed to accompany a «/ 

dynamic value header. A cmDefineObjectQ call always initializes the umon field */ 

/* to NULL on the assunqttion a ''oormaT value header is being created. Only in here */ 

/* do we aeate d|ynamic value headers. Thus only in here do we fill in these fields. */ 

We just got done creating the dynamic value header. So fl^ first *>'"ig to do is */ 

/• to allocate its extensions data. So here goes... «/ 
if ((extensions = (DynVdueHdfixtPtr)CMmaIloc(sizecrf(I)ynWucHdiExt))) = NULL) { 

typeNaroe = cml6GlobaINameObject(type, CM_StdOt5lD_GlobanypeNamB); 

ERROR2(CM_eir_NoDynExtensions, typeName, CONTAINERNAME); 

return (NULL); 

} 

/* Point the extensions union ahemafire at the extensions space we just alloacted. */ 

/* Also, while we're screwing around in the dynamic vahie save the refCon passed in. ♦/ 

/* The vahieRcfCon field is convenient so that CMOet%hieRefCQnO will be abk to be */ 

/* used by the dynamic value handlers just as it would with normal values. */ 

DYNEJCIENSIONS(theDynamicWueHdr) = extensions; /* pomt at the extensions data */ 

thcDyc2micValucHdr->vahieRefCon =refCon; /♦ remember tte rcfCon */ 

thcDyoamicValueHdroiiseCount =1; /* set use count to 1st use ♦/ 

We now must init the extensions fields. Among the fiekls are the dtynanuc value */ 

/* handler pomter vector (our *V-table*'). It oonsisls of the pointers to the v 

f* corresponding value operation handler, a "piDtect^from-recur^e.use'* fl^ and «/ 

/♦ the value "thi^ pointer. We init all this stuff to NULL and "not calletT. The */ 

/* metahandler passed to this routiiK will be used to fill in the handler pointers on «/ 

/» first use (see cmGetDynHandlerAddiessO). It will set the **this" pointer too. */ 

/* To make it easier to init in tlv vector, the following macro is used: */ 
#define ImtDynVector(h) extensions->dynVahieVcctoriLhandler NULL; \ 

extensioiis->dynValueVectDrii.(iu3Valw = NULL; \ 

e:^nsions->dynVaIneVectorii.«ctxve = false; 
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fiiitDynVectoi(cniGct'^wSizc); /• prepare handler vector... */ 

]mfDyiiVectoi(cmRead>^ueData); 
£u!DyiiVectoi(cmWnte\^iueData); 
iaiiDynVcctor(cmiaseTtVahieData); 
Iai(DynVectoi(cinDeleteValueData); 
IIUiI>7I^VectoI(cmGet^^hleIIl£b); 
]miI>yjiVcctoi(cmSct\WueTypc); 
lmfDynyectoi(cmSet\^ueGcQ); 
]iii(DynVectoi(cinReLcaseAi^UB); 



extensioiiS'>inetaHaQdler = roctaHasdter; /* lemember metahaodler a<Vl r'^< */ 

extensiaiiS'>baseVaIue = baseWueHdr, /* point dyn value hdr to its base */ 

/* For layeriDK dynamic values, a backwaid chain of dynamic value l^adeis is fbnned */ 

/* bom the new (lynauuc value header back to the ari^nal **tear* value header. The */ 

/* link is the baseValue extensioDs field set above. It always paints to its base *J 

/* value (it is also used by CMGetBase'SUueO). As meptifmrd above, the dynValue */ 

/* union altematiye in a Seal" vahie header always points to the last dynamic */ 

/• value of the chain. A CMUseVahieO or CMNewValueQ ^31 always return the pointer */ 

/* to ^ dynamic value at the eiKl of the chain. So, we always want to set tiie */ 

/* dynVihie pointer to the now dynamic value header we created above. Note also we */ 

/• use this pointer to make sure the value passed as a base to us here is indeed the */ 

/* pointer to the end of the chain. We <fid this check near the start of this routine. */ 

/* From that check wc get the pointer to the original '^teaT value. So now we can ♦/ 

/* set that pointer to the new end of chain. ♦/ 
thcReaIV4hjeHdr->dyaVahieData.dynValue = tteDynamicNWucNdr, 

/* Layered d|ynamic values, i.e., dynamic vahies that have a dynamic value base are V 

/* NOT treated as distinct vahies for special property whose chain we pat them on when */ 

/* we did the cxnEtefineOlijectO above. This means we must take such a vahie OFF the */ 

/* special property chain. It's not getting ksst though. Remember we just got done */ 

/* pointmg the •*icar* value dynVahic at it Note, we flag this value healer as •/ 

/* being off the chain. This makes it a simple test later when we want to delete */ 

/• these piqjpies off the layering chain (dene by CMRelease\Wue()). ♦/ 

if (I firstiy^iamicValue) /* do only if not the first timo ♦/ 

cmDeletcListCeU(*iheI)ynan]ic\WueHdr->theProperty->vahieH^ theDynamicValiieHdr); 

cmNutILisfUnks((beDynamic\UueHdr); 

tfaeDynamicVahieHdr->value!Flags J= ValueOflEPropChain; /* mark as off the prop, chain */ 
} else /* if we have a NEW dynamic vahic... */ 

^-KOQtainer->taigetContaincr->nbiOfDyiiValnes; /* ...keep count in targetContaincr */ 

letom (theDynamicValueHdr); /* give caller the dynamic value */ 

} 



Returning to the AH calls, CMGetNextValue () is defined 
next: 

40 

CMVahie CMGetNextV»hie(CMObject object, CMPtopcrty property, 
CMWilue cuirValue); 



This routine returns the refNum for the nejct value 45 
(according to the current value order) in the objects projKrty 
following currValuc. If cuirValue is NULL, the refNum for 
the first value for that object's property is returned. If 
cuirValue is not NULL, the next value for that object's 
property is returned. NULL is returned if there are no more 
type values following currValue or the object does not 
contain the property. 

currValue is generally a refNum previously returned from 
this routine. Successive calls to this routine wiU thus yield 
all the values for the specified j^opeity of the spedfied 
object as long as no other operations change the value order. 55 



CMVahie CMNewvahie(CMObject object, CMPtopcrty property, 
CMiypc type, ...); 



A new entry is created for the designated object, with the 
designated property and type and a return to the entry is 
returned. The generation number of the value defaults to the 
generation number of the container, but it may be set with 
CMSetValueGeneration. 



An object's properties can have more than one value. 
However, the all the types for the values belonging to a 
given object propwty must be unique, fi is an error to 
attempt to create a value for a property when there is already 
a value of the same type for that property. 

If the specified type corresponds to a global type name 
that has an associated **use value" handler, or if its base types 
(if any) have associated **use value" handlers, a dynamic 
value wUl be created and returned. The value will be 
initialized using the datalnitE^ams arguments, which must 
correspond to the initialization arguments for a value of that 
type. 

Note that the value refhum at this point has no associated 
data. The value data is set with CMWriteValueData or 
CMOpenNewContainer (to write an embedded container). If 
the value will be used as an embedded container it must have 
the embedded container type. Using CMWriteValueData on 
a value of this type is an error. 

The value is aeated at an unspecified location in the 
sequence of values for the specified property. Creating a new 
value may cause the order of the values for that property to 
change. 

The CMNewValue() routine is implemented merely as a 
wrap around the CMVNewValue() routine, described below. 
The CMNewValue() routine merely does what a user would 
do to use CMVNcwValucO: 
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C3dWh3e CM_VARARGS CMNcw"%luc(CMDbjcct object, CMProperty property, CMiype type, .„) 
{ 

CMValue value; 

v» lie * datalnitPsinuns; 

v4_start(databiitParams, type); /* get ptr to the parameters */ 
vahiB = CMVNewVah]e(object, property, type, datalmtPaiams); 
vQ.eiid(dataiaftPaxams); 
letum (vahie); 



CMVNewValueO does the same as CMNewValueQ either a aew object (id) or a preexisting one for which a new 

above, except that the dynamic value data initialization (ie., property and value arc to be defined. All the fields for a TOC 

. . " ) parameters are given as a variable argument list as entry are passed. The objectFlags indicate the type of the 

defined by the "stdarg" facility. D assumes that the caller has object, 
set up and terminated the variable arg list in the manner 

shown above for CMNewValue(). CMVNewValueO is Note, the value associated with the property is appended 

implemented as follows: to the end of the property's value list. The caller has the 
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CMValue CMJKEDARGS CMVNcwValueCCMObicct object, CMEroperty property, CMiype type; 

va_list data&utParams) 

{ 

TOCOlgectPtr thcOtoect; 

TOCValueHdiPtr theWucHdr, baseVUueHdr, 

ConlainerPtr cantBiiier; 

ExitKBoIObjcctCobjcct, NULL); /• validate object •/ 

ExitKBa(iProperty(property, NULL); /* validate property */ 
ExitIfBanype(type, NULL); A* validate type ♦/ 

container = ((rOCObjectptr)object)- 
>coiitainer, 

if (coiitaiiier->targetCGQtainer != 

((TOCObjectPtr) p ro per^ )->ccgi t a i Der->targetCoiitaiDer il 

coiitaiiier->taigetCoiitainer 1=: 

((TC)CObjcctPtr)typc>>container->tarsetCaiitaiiKr) { 

ERROR3(CM_cir„3Containcis, CONTAINERNAMEx(container), 
CONlAINERNAMEx(((TX>CObjectPtr)piaperty}->oQiitai]»r), 
CONlAINERNAMEx(((lXXX)bjectf>ti)type>>cQntainsr)); 

retum (NULL); 

container contaiDer->updatingCaniaiiier; /* use updating container from here on 
*/ 

f* Hiis will create a value header far an existixig object or a new ol^ect widi a 
vahie header but no value. Other **CM.." calls will create the actual vahie(s). 
•/ 

theObjoct = cmDcfineObjectCcontaiDei; ((TOCObjectPtr) ob}ect)->objectID, 

((TOCObjectPtr)propcrty)-X)bjectn), ((TOCObjectPtr)type>.>objectID, NULL, 
contaiQer->geneiatioii, 0, ObjectObject, &fheVaIueHdr); 

if (theObiect = NULL) retum (NULL); 

/* Check to see if a dynamic value must be created. This is done by caHing 
cmFoIlowBaseiypesO to do a depth-first search starting horn the given ty^ on 
all of &at type's base types. Dynamic values are created for each type that has 
a **nse value" and "new value" handler. Hie resulting (tynamic vahie is returned 
or the "rear value we created above if there axe no dynamic values. 
baseVahicHdr = tteVahieHdr; 

thcValueHdr = cmFollowiypes(the%IueHdr, (T0CObjectPtr)typo, true, 

ftdatahiilPaiams); 
baseVahieHdr->useCount 1; /* set use count of **reai" vahu */ 
return ((CMValue)theWueHdr); /* retum real or dynazmc value*/ 



The cmDcfineObject() routine, used in the above code, is option of getting the pointer to the value header 
called to dcdne a new TOC entry for an object We may have (theValueHdr) when theValueHdr is not passed as NULL. 

The format of the cmDcfineObjectO function call is: 



TOCObjectPtr ca]I>e£tneObject(ContainerPtr container, unsigrvd long objectID, 
const unsigneH Icmg propertylD, const nn^gn^ lopg typcID, 
TOCWueBytesPtr value, const unsigned long generation, 
const unsigned short flags, const un^i grM short objectFlags, 
TOCV^iKHdrPtr •theVahjeHdr); 
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The function returns a pointer to the object if it was 
successfully created and NULL if it wasn't. An error is 
reported if NULL is returned. 

The objcctFlags dctcnniac how the function treats the 
object and all the object fields (the other parameters). There 
are four possible objectFlags: 

(1) . UndefinedObject Set if the object is to be created, but 
we don't yet know what its TOC entries are. Basically 
a null object (or placeholder) is created. It is an 
incomplete object in that there arc no properties or 
types chained to the object (yet). This flag may be used 
in combination with the others if we know that the 
object ID corresponds to a property, type, or neither. 

(2) . ObjectObject.This flags is used when we don't know 
the type of the object but we know a property and type 
for it If the object already exists and it's undefined 
(UndefinedObject) it is now considered as defined. If it 
was an undefined property or type, it now becomes a 
defined property or type. Of course, duplicate defini- 
tions are an error. 

(3) . PropertyObjecL This is similar to ObjcctObject, but 
here we know the object is for a property. It has to 
cither not exist previously, or was previously flagged as 
UndefinedObject and PropertyObject. 

(4) . lypeObject Same as PropertyObject, but for type 
objects. 

Returning again to the Value Operations, value data can 
be read using the following API call: 



CMSize CMRcadVahieData(CNfValuc value; CadPtr buffer, 
CMCount offset, CMSize nBiSize^ 



The data, starting at the offset, for the value is read into 
the buffer. The size of the data read is returned. Up to 
maxSize characters will be read (can be 0). 

The data is read starting at the offset, up to the end of the 
data, or maxSize characters, whichever comes first Offsets 
are relative to 0. If the starting offset is greater than or equal 
to the current data size, no data is read and 0 returned. 

is an error to aOtmpt to read a value which has no data, 
ie., a value where only a CMNcwValue has been done. 

FIG. 8 is a flowchart of a CMReadValueDataQ routine 
800. In a step 802, the routine first determines whether the 
value designation whidi was passed to it is a valid value, and 
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if not, it exits. In a step 8M, the routine determines whether 
the value is a dynamic value or not If it is not a dynamic 
value, then the routine merely obtains the real value &om the 
real value segments (e.g. 426) and assembles them into the 
5 caller*s buffer (step 806). It then returns to the caller (step 
808). 

If the value is a dynamic value, then in a step 810, the 
routine obtains the dynamic handler address of the read 
handler associated with this value. To obtain die dynamic 
handler address, the routine calls a 
cmGetDynHandlerAddressO function (described below), 
passing fee value, a pointer to fee dynamic handler vector 
entry for fee desired read handler, and an indication that it 

J 2 is a read handler which is being sought If this was not fee 
first use of fee handler, fee cmGetDynHandlerAddressO 
function returns fee desired handler address from fee vector 
entry specified in fee calling parameters. If it is fee first use, 
then fee function finds fee inherited handler address and 

20 returns it 

In eifeer case, fee value may have changed, so in a step 
812, fee CMReadValueDataQ routine 800 checks again 
whefeer fee value is still a dynamic value. If not feen fee 
real value is assembled (step 806) as previously described, 

25 and remrned in fee caller's buffer (step 808). 

If fee value is still a dynamic value, feen fee routine 
signals feat fee dynamic read handler for this value is in use 
(step 814). This step sets a flag specific to the value and fee 
read handler of that value, which is used to detect an error 

30 by recursion. 

In step 816, anofeer flag is set which allows getting base 
values in fee present container. Only dynamic value handlers 
are permitted to get base values, since base values are not 
defined for real values. 

35 In step 818, fee actual read handler routine is called as a 
procedure. The address of feat routine was placed in fee 
value's dynamic value extensions vector previously in step 
810. 

In step 820, fee routine disallows getting of base values in 
^ this container, and in step 822, it signals that fee (fynamic 
read handler for this value is once again available. The 
routine fean returns wife fee requested data in fee caller's 
buffer (step 808), as placed feere by step 818. 

The following C-language code implements 
CMReadVaIueData(); 
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CMSize CMLFIXEDARGS CMRcadValiieDaU(CMValiie value. CMPtr buffci; CMCount ofl&et. CMSize 
mazSize) 



container, 

♦p; 

len, remainiDg, totatRead, anvuntRead; 
/• validate value */ 



TOCVahjeHdtPtr theVWueHdr; 
TOCVafaePtr flie\Wue; 
CoDtainerPtr 
unsigned char 
unsigned long 
ExitIfBadVahie(value, 0); 
container = ((TOC%i«HdrPtr) 
value>.>containcr, /* NEVER use 
updatingCoatanxr 
here*/ 

if (IsD7namicValue(vah]e)) { /* process dynaizuc value... •/ 

GetDynHandlexAddre33(vah£, cmRcad^ucData, CMRcadVabeDataOpiypc, 

«CMRead\WucData'*, 0); 
if (IsDynaimcVa]ue(vahje)) { 

SignalpynHandkrljiUseCvalue, cmReadValueData); 

AUowCMGefBaseValtie(container); 

totalRead = (unsigned lDng)CMDynReadWueData(vah3e, buffer, 
offset, maxsize); 
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DisAliowCMGetBa$e^lue(coiilainer); 
Signa]DynHa]]dlerAvaiiable(vaIue, cmReatH^lueData); 
return (totalRcad); 

} 

} 

the^^dueHdr = (TOCValiiBHdiPtr)valtie; /* Hhis") value may hsvt changed */ 
if (maxsize — 0 li bufifer ^ NULL) return (0); 

/* Scan across the vahie list for the value header and coscat data into buffer. 
A value list 'vill exist for continued values. The user views the data as osie 
contiguovs chunk of stuff. But a continued vahic is actually a set of 
ooQ-contiguofas smaller chunks that we concat into the user*s buffer. Hie user 
specifies a starting oSset with xcspoct to bis or her view of (be contiguous 
data. We must map that offset into an o&ci within the proper staithig 
contiDned value segment The mapping is done by cmGetStaiting\^IceO. */ 
if (cmIis£iiiptylJst(&theVahieHdr->vahiBList)) { /* must have a vahie V 

ERRORl(CM-jenLjIasNoWue, CONTAINERNAMB); 

return (0); 

} 

theWoe = cmGetStartingVahie(ti)eVahieHdr, ofEset, &offset); /* get start 
seg/offset */ 

if (theValue = KULL) letum (0); /* oSset out of range */ 

P = (unstgned char *)buffer; /* p points to next byte to read to */ 

remainiqg — (unsigned long)maxSize; /* remaining bytes to read */ 
totalRead = 0; /* how much wc actually do read */ 

while (the\Uue && icxnuning) { /* read value (segments)... */ 

Lcn = cmOetIValueSize(thc\^ihie) • offset; /* (note^ immediates woric hcic) 
*/ 

if (lcn > remaining) len = remaining; /* (note, so do global names) */ 
if (ten) { /* if more is wanted... ♦/ 

amotmtRead = cmReadlValueData(thcWue, p, ofi^t, len); f* tead 1 
value segment */ 

totalRead -Hs amountRead; /* keep track of how much we read */ 
if (amouQtRead < len) break; /* if end of total vahie^ we*re done 
•/ 

p 4= len; /* point at next &ee byte m buffer */ 



} 



= 0; /* full segments &om now on */ 

remaining -« len; /* adjust what's remaimng to read */ 

theVelue (TOCValtuPtr)cmGetNexa^istCeU(theVah»); /* point to iwxt 

value seg */ 

} 

return (totalRead); return total amount concatenated */ 



The IsDynamicValueO call made by the above 
CMReadValueDataO routine is the macro defined previ- 
ously which merely checks the appropriate flags for the 
value. The GetDynHandlerAddressQ call is also a macro 
defined previously, which calls a 
cmOetDynHandlerAddressQ routine. 

The call to cmGetDynHandlerAddrcssO is of the form: 



CMVolue cmQetPynHaodlec^ddress(CMN^lue value, 
DynamicWueVectenEntncsPtr vcctocQntry, 
CKfooosL-CMObbalName opczatioinVFe. 
char *toutineNaiiie); 



A dynamic value handler is callable if it exists (of course) 
and it is not being used recursively. The vectorEntry points 
to the dynamic value entry in its vector belonging to the 
extensions of the passed dynamic value. If this is not the first 
use of the handler, the vector entry contains the handler 
address and its associated f this**) value (discussed below). 
If it is first use, cmGetDynHandlerAddrcssO must find the 
('^inherited") handler address and its associated *this" value. 
In either case, the **this" value is returned as the function 
result. NULL is returned if an error is reported. 

The returned value, and the one saved in the vector entry 
may not be the same. They are the same if the passed value 



already has a handler. If it doesn't, an '^inherited** handler, 
from one of the dynamic valuers base values is used. The 
value associated for whoever has the handler is the "own- 
ing** value. In C++ terms, it is the •*this" pointer. In the limit, 
we could end up using the original **real" value that spawned 
the dynamic value(s). If that is indeed the case, we end up 
using the calling routine which will always be an API value 
operation. 

50 The found handler address and **this" pointer are saved in 
the passed dynamic value's vector entry so we don*t have to 
do the seardi on successive uses. The **this" pointer and 
handler address are also saved in the vector entry cocre- 
spending to **this" (unless, of course, it is the **real" value). 

In the vector entry there is also a boolean flag that tells us 
whether tiie handler is cuirently active, Le., in the call chain. 
If it is we have a recursion attempt Hiis causes an enOT 
rqx)rt and NULL to be returned. Since we will always find 

^ the handler or use the **real** value, we can never get an error 
from that. The recursion is the only error condition. 

cmGetDynHandlerAddressO can be in^lemented as fol- 
lows: 
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CMValix cmGetDyiiHsDdktAddiessCCMVilue value, Dynamic Value Vcc toiEntricsPtr vcctoiEntry, 
CMcoosL-CMOkibalName operationiype, char *iDUtuicName) 

{ 

hong enlryOfiGset; 
CMValiie orig\Wuc; 
CoDtaiueiPtr container; 
CMHandlerAddr handler, 

/* It's an eizor to atteiDpt a recuifiive call.. */ 
if (vecto!Eiitiy->«ctive) { /* ciror if recuising... *f 
cantainer « (C^OC^WuoHdrf>tr>value)->containcI; 
ERR0R2(CNL_eir_HandkrRecurscd, loutineNamc, CONTAINERNAME); 
return (NULL); 

} 

/* We ate not recuxsiiig and this is not the filist time we're usiog this handler, just */ 
/* return the "this" pomter associated with the handler we found on an earlier call. */ 
/* They were initialized to NULL when the vector was allocated We cannot test tlK */ 
/* handler pointer because it will not be set if the "this" pointer is for a base */ 
/♦ -rear* vahie. 

if (vectorEntry->thisVahK != NULL) return (voctocEntry^thisVahje); 

/* Ihis is the first call to the handler. We now must search vp die dynamic value */ 
/* chain, starting with the passed dynamic value. Looking for tiu £rrt dynamic value */ 
/* diat sillies Ihe handler. Ihe handler is accessed in tbe usual way via its dynamic */ 
/* vahie metahandlcr. «/ 
orig\^lue = value; /• remember stardng dynamic value ♦/ 

for (;0 { /♦ loop till we find the haailer„. */ 

handler ^ (CMHaodlciAddr)(*D7NE3nENSK)NS(vahie>>mctaHandlcr)(NULL» 

opcrationtype); 

if (handler 1= NULL) brealc; /* break when we find tl» handler V 
/* If not found, we must get the current value's base value. can do this until */ 
/* we reach the original "^reaT' vahic. If we do reach it, then that stops the search ♦/ 
/* and it is the '^aT' value we return. In that case, there is no handler because */ 
/* tbe calling API vahic routine will directly operate on the valtr. Thus we leave */ 
/* the handler address in tbe original value alone. Of course we set Il» '*this** */ 
/* pointer. The next time the dynamic value is used, we will return ttK **real*' */ 
f* value. As discussed in DynamicVahiesii, the caller tests the returned value */ 
to see if it is still a cfynamic value. If it isn't, the handler use is bypassed. */ 
value = (CM%lueXDYNEXIENSIONS(vahK)->baseVaIue)y* basically a •/ 
CMGetBaseA^C) 

if (IIsDynamicN%hfte(vahie)) { /* if we reached the "real? value... */ 
vecto£ntry->diisVahie = valued* save "ihi^ value for next tinw- */ 
return (value); /* return the '"reaT* vahie as **this^' ♦/ 

} 

} /* for */ 

/* Set the **tliis" pointer and handler address in tbe original vector entry for tie «/ 
/* next tune we tise it. Note that we can only exit tlK above "for"' loop if we find */ 
/* the handler. If we loop up to the "real" value without fiiKjling it, we exit tiie */ 
/* ttnitiiie from inside tie Loop a&er saving & **thi^ pointer as we do here. */ 
vectorEntry->thisValue = value; /♦ icmember "this" */ 

vectorEatry>>handkr = handler; /* remember its handler address */ 
/* Just to be safe, we want to copy tie "this" pointer and handler address in the */ 
/* vector entry corre^onding to **this". Of course wo only need to do ttiis if we */ 
/« '^inheritecf a handler (Le., we looped up to a base dynamic (but not real) vahie. */ 
/• Note, this is where we do the struct ofifeet relocation warned about earlier. */ 
if (value != origVahr) { /* if "interited".,. */ 

entryOfbet = (char •)vectoiEntry - (char •)DYNEXIENSK)NS(origVyuc); /• reto- */ 

cate... 

vectorEntiy = (DynanucValueVectoiEntriesPtrX(char ♦)DYNE?nENSIONS(value) + 
enlryOffset); 

vectorEntiy->thisVahje = value; /* set *'thi5"8 vector entry */ . 

vectorEntry->handlcr « handler, 

} 

return (value); /* return **thi5" ♦/ 

} 



Returning again to the Value QperatLons, the con^lement 
of CMRcadVaiucDataO is CMWritcValueData(). In 
CMWriteValueDataO, the buffer specified by the caller is 
written to the container and defined as the data for the value. 
If the value already has data associated with it the buffer 60 
overwrites the "old" data starting at the offset character 
position. Size bytes arc written. Size can be 0. 

If the current size of the value data is S (it will be 0 for 
a new value created by CMNewValueO). then the offset 
passed by the caller may be any value from 0 to S. That is, 65 
existing data may be overwritten or the value extended with 
new data. The value of S can be obtained using 



CMGetValueSize(). Note, no "holes" can be created. An 
offset cannot be greater than S. 

Once data has been written to the container, it may be read 
using CMReadValueData(). Note that CMReadValueDataQ 
is also used for containers opened for input using 
CMOpenContainer(). It thus can be used for all kinds of 
opens. The converse is not true. CMWriteValueDataQ may 
only be used for a container opened for writing (or 
converting) using CMOpenNewContainer(). 

CMWriteValueDataO calls for a particular value do not 
have to be contiguous. Writes for other values can be done. 
The APL specifically, this routine here, talccs care of gen- 
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crating "continued" value data (segments) for a value. The to view the data as contiguous. The input offset is mapped 
data is physically not contiguous in the container with such into the proper starting segment and offset within that 
a case. GMWiiteValueDataQ hides this by allowing the user The following routine implements CMWriteValueDataQ: 



e 1992 Apple Computer, Inc. 

void CM_PIXEDARGS CMWiteVahjeDate(CM\^h» value, CMPtr buffer, CMCouut oflfect, 
CMSize size) 

{ 

TOC^^ahicHdtPtr dttV^ueHdr; 
TOCVahePtr thc\Mac, (lieNextVauc; 
Omt^BciPtr container; 
uosigDcd char *p; 
cbar offsetStr(151: 

un^gsed kmg Icn, remaining, amounfmtteo, next&ee, valneSize; 
TOCValueBytes vahieBytes; 

Exitrfflad%hie(vahifi.CM_NOVALt]E); /• validate vahie •/ 

if (bufEcr = NULL) return; 

theWucHdr = (TOC\WueHdrPtr)value; 

contaiDer = tfaeWueHdr->container->i9datmgCoQtainer, 

if ((contaiDer^useFlags & IcCMWritiitg) = 0) { /* make sure opened far writh^ *f 

ERRORl(CM_err_WfiteIllegall, CONTAINERNAMH); 

return; 

} 

if ((tbBValueHdr->vahieFUgs & VatuePiDtected) 1== 0) { /* can^t write if 
protected! */ 

ERRORl(CNL_en_WriteIllc^. CONIVMNERNAME); 
return; 

} 

If ((tbeWueHdr->valueFlass & YalueOloba]) 1= 0) { /* can't write ta global 
names •/ 

ERRORl(CM„eir„CantTOtcGIbl COKDUNERNAME); 
letum; 

} 

if (IsDynamicVklue(value)) { /• process djmamic value„. */ 

GefDynHandlerAddies$(vahie, cmWiiteVUueData, CMWhteValueDataOpiype, 

"CMWriteValueData", CHJJOVALUE); 
if (bI>yDaiQic>^hie(vahi&)) { 

5igDaI]>ynHaDdlezbilJse(value, cia^Ute^hjeData); 
AllowCMGeffl8seValue(cQntaiiwr); 
CMI>yn^S^WueData(raIue, buffer, offiset, size); 
Di3AUowCM0ctBaseyalue(container); 
SigDalDynHaidlerAvanable(value, cm^^iteValneData); 
retnm; 

} 

theYihieHdr = cr0CValiKHdiPtr)value; /* (^his") value may have changcdl 
♦/ 

} 

/* If the value list is eap^, create the first or only value for this value 
header. An imtnediaTft value is created if flae vahie size is less than or equal to 
the sizeof(CM_lILOKO). Ott^rwise we write the data to the cootmer and set the 
TOC info with the o&ct to it. */ 

if (cinIsEn)Lpt3^ist(&tbeVahieHdr->valueList)) { /* if we have a value list.. 
*/ 

if (of^t > 0) { »jcieate initia] value V 

ERROR2(CM_erT_offset2Bi& cmItostr(offset, 1, false, ofifeetStr), 

CONIAINERNAME); 
return; 

} 

if (size <= 6izeof(C£(_I3LONO)) { /* we can make value immediate... */ 
{void)cmSetVahieByte5(containeri ftvalueBytcs, Valuc_Jimn„Chai3, 

(unsigned lQng)buffei; size); 
cmAppeadValuc(theVaIucHdr, &vahiebytes, kCMhmncdiate); 

} else if (size 1= 0) { /* value must be written.,. */ 
#ifO 

nezff'ree = CMgetCQntaiDerSizc(containcT); 
CMfseek(oQntaiDcr, 0, kCMSeekEod); /* positioa to cuneot eof */ 
if (CMfwrite(contaiQer, buffer. azeofi[unsigned char), ^) 1= 
size){ 

ERRORl(CM_cnJadWiite, CONXAINERNAME); 
return; 

} 

(void)cmSetValueBytcs(coniaincr; &valueBytes, ValueL_Notfinm, 

ncxtFree, size); 
cmAppeafS^ahie(tbe:VahieHdr, ftvaloeBytes, 0); 
container->physicalEOF = xxxfPtec + size; A* update next free 

container byte */ 

SctLog?caLE0F(caataincr->plty5icaIEOF); /* Logical EOF = physical 
EOF*/ 
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#eixlif 

if ((CMSize)cmmteData(fiKVaucHdr, (unsigned char *)buffer, 
(unsdgDed Ioiig)sxze) 1= size) 
ERRORl(CM_cn_BatiWrite, CONTMNERNAME); 

icturo; /• «dt */ 
} /* end of 1st ysiIik */ 

/* At Ibb pcnnt we have EXISTINQ data (possibly already contiiiued). If the 
ofket says that we axe NOT writiiig to the cud of the data* tbea we MUST be 
overwriting sooie of the existhig data. In other words, the offiset must be less 
than the total size or we have an esor. We can otdy overwrite or append {ue^ 
coocat). caimot create a "hole**. In tl£ code that follows we consume enough 
of Gxt input buffer to do the overwriiiog staring at the offset. If we consume 
it all, we're done. If not, we have reached the end of the existing vahie aol we 
degenerate into the concat case. */ 

valueSize = CMGetVdueSi2e((CM\^)tfaeVah3eHdr); /• get current eaze of vahie */ 
if (valueSize 1= offeet) { /* here we must be overwriting... */ 

if (rouchlt(container, tbeVaiuBHdr->comaiQeT)){/* if recording i^tes... 
*/ 

CMDefeteWueData(vahic, ofEset, size); /* ...do overwrites this 
way! */ 

CMIascrtVaIaeI>ata(valuc, buSiert offset, aze); 
return; /* wc*re through */ 

} 

theValuc = cmGetStartingValue(tteValucHdr, offset, &offiset): 

if (thcVahie = NUIi) { /* ofeet MUST be IN the value ♦/ 

ERROR2(CM_cir_Offiset2Big, cmltostr(offiset, 1, false, ofeetStr), 
CONTAINERNAME); 

Tctum; 

} 

p = (unsigned char *)bu2er, /* p points to i»xt byte to write 

*/ 

renoaining (unsigned lDng;)size; /* remaining bytes to write */ 

while (theValue && remaining) { /* overwrite existing value data */ 
theNertWue = (TOC\WuePtr)cmGett^extListCell(the\Wue); /* get 
next value seg *f 

Len = cniGetlVahieSi2e(theWue) - offset; /♦ (note, immediates work 
herel) */ 

if (lea > remaining) len = remaining; 

amountWritten = cinOverwritelValirJ)ata(tlK:'%lue, p, ofEset, len); /* 

write 1 acg. */ 
if (anoountwritten = 0) return; 
p += amountWitten; 

offset — 0; /* full segments from now os */ 

remaining amountWritten; /* a^iust what's remainiiig to write */ 

theVahw = thcNext^ue; /* point to KXt value seg ♦/ 

} 

if (remaining = 0) return; /* yikesi all of it was written! V 
size = (CMSize)rcmaiimig: /* prepare to write rest at end •/ 
buffer = (CMPtr)p; /• simply fall through to iKXt case */ 
} /* end of overwriting existing vahie data */ 

/* At tlus point we want to concat the ikw data on to the end of the existing 
data. We are doing this because die ii^ offset was equal to the data size or we 
ftW. through from above because there are still more bytes to write in an 
overwrite and these bytes **stick" off d» end of the current data. Again this is 
a coEcat case. Neat isn't it? 

Wen, actually no! Unlike the code above here wc must handle immediate data 
explicit^. It's sort of a hassle. Tbaf s because the annunt of lew data to 
concat to an immediate might mean that it can't be immediate any moic. Immediate 
data is Limited m size to kss than or equal to si2eofi[CM_ULONG). If we can 
cram tiie new data we do it. If we can't, then we must convert die immediate to a 
ncD-immediate by writing the data to the container and changiag its TOC info to 
be and of^t We then have a non-inmiediate which falls dnougfa to the standard 
coQcat code for non-inunediates. The way all these cases "falT into one another 
is the **iiear thing here. 

thcA&hic = (T0C^Wl»Pl^)cmC3cfLisf^ail(&lteVahleHd^->valucUst); /♦ use tail of 
list •/ 

if (theValue->flags & kCMImn»diate) { /* if current value immediate... */ 

if (valueSize + size <= si2eof(ClIl_ULONG)) { /*cram new data if we can..*/ 
if (size > 0) { /* there must be some data to write */ 

memcpy(tbeValue->value.iinin.ucharsValue + valueSize, 

(char *)buffier, (size_t)fflze); 
theVahie>>vah]ejiotIaun.valueLen ~ vahicSize + size; 
tfacValucHdi->size +<= size; 
cnflbuchTminMtiafeValue(theValueHdr): /* touch for 
\q>datiiig if necessary */ 

} 

return; /* that's all we ived to dol */ 
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} 

if (lcmConvext&]3iDediate(&e'\^lue)) /* ooavort ihc tmmrdiate... */ 
return; 
} f* end of nnmediatc */ 

/* We are now ready to coocat the new data on to the end of the easstiog data. 
Here too life is not simple. A ^'ooncaf * means hero means a (^sical ccmcat if 
the old data was the last thing written to the SAMEjContainei. If it wasn't we 
must create a new value eotiy on the valueHdr's value list to represent a 
contimied value. Note the euqifaasis on "SAMF* container. We could be writing 
updates for an "old'container to be recorded in a new updating containeT. 
nextPree = CMgetContaiDeTSize(contaiiier); 

if (tbeVali]e->vah]ej]otIinm.vatue + tiieValue->raIue.ix)tImm.valueLen = nexO^ && 
tfaeValuB-:>containeT =: container) { /* must be SAME container! 
»/ 

if (size > 0) { /♦ there must be some data to write ♦/ 

CM&eelc(cantaiDer, 0, kCMSeekEnd); make sure of container 
position */ 

if (CMfwrite(coiitainer, bufier, sizeof(ims'^gn6d char), aze) 1=^ 
size) •[ 

ERR0Rl(CM_ert_39dWritc. CONIAINERNAME); 
return; 

} 

container->^ysica(EOF = nextPree + size; /* update next free 
CQDtaiDBi byte */ 

S6tLo£icaCEQF(contaiaer->ph7sicaLEOF); /* bgicalEOF = physical 
EOF*/ 

thBVahK->ralttejiotl2mn.valueIjcn -h^ size; /* update total size */ 
tbeVaLueHdr->size -fc size; /* keep size m valxicHdr in sync */ 
cmTouchEditedVahie(theWueKdr);/*toach for i^dating if necessary*/ 

} 

letum; 

} 

/* Too badi We couldn't realty do a concat. We must create a conUnued vahie..*/ 
#ifO 

theWue->flags t= kCKKontimied; J* fiag the current value as cont'd */ 
theWueHdr->valueFlags l=VilueCantinued; /* also set a more convenient flag */ 
CM&eek(containeiv 0, kCMSeek£nd); 

if (CMfvraite(coiitaiaerf bu&r, 6izeaf(uQsigned ch&rX size) \= sac) { 
ERRORl(CM-_eir_BadWrite, CONTAINERNAME); 
return; 

} 

container->physicaLEOF - nexff'ree + size; /* i^datc next fiee cantainer byte */ 
SeflLogicaiLEOF(containcr->pliy5ica(EOF); /* logical EOF = physical EOF */ 
(void)cmSet^^tusBytes(ooui:ainer, &valueBytes» \^ue_NotIinm. nexfPree, size); 
cmAppei]dWuc<lheValueEdr, &valuebytes, 0); 
#endif 

if ((CMSize)cmWriteData(theValueHdz, (unsigned char *)buffet; (unsigned 
bng]size) )= sazxt) 

ERRORl(CNL_err_BadWriJB, CONTAINERNAME); 
/* If we're recordii:;g updates, then define touched list enh^ for the write... */ 
if (st2e > 0) cmTauchEditedWue(theValueHdr)-/*touch for updating if lecessary*/ 



In addition to the above, it will be usefiil to point out 
certain other API calls supported by the CoDtainer ManageL 
More detailed descriptions of the implementation of these 
calls are unnecessary, however, since the descriptions above, 
together with the additional information set forth herein 
about the Container Manager, are sufficient for a person of 
ordinary skUl to understand the invention. 



VOID CMInsertWueI>2ta(CMVat» vahie, CMPtr buffer, 
CMCount offset, CMSize size) 



The buffer is inserted into the value's data at the specified 
offset size bytes arc inserted. If the current size of the value 
data is S (it will be 0 for a new value created by 
CMNewValueO), then the offset may be any value from 0 to 
S. That is, the insertion may be anywhere within tiie data 
value or the value extended with new data. The value of S 
can be obtained using CMGctValueSizc(). Note, no *1ioles" 
can be aeated. An offset cannot be greater than S. Also, an 



insortion at offset of S is identical to a CMWritcValucDataO 
to the same place. 

Once data has been written to the container, it may be read 
usin^ GMReadValueDataQ. 

From an implementation point of view, continued (i.e., 
segmented) values are handled by splitting them into one or 
two new segments. Hie insertion is always a new segment 
The original segment to be inserted to will split into two 
segments if the insertion is in to its middle. It will remain 
intact and unsplit if we are inserting into its beginning. The 
new segment is simply insarted in front of it. For the split 
case the new segment must be inserted between the split 
pieces. 



VOID CMDelete\^hrOata(CM>^ vali», CMCount ofbct, 
CMSize size) 



Let S be the length of the value data. The bytes from offset 
to offset+size are deleted from the value, and the value is 



55 



60 
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"closed up". After this operatioa, the size of the value data loutine docs not need to be used since the value inherits its 

is S-size (assuming offset+size is 2 S). If offset is greater generation from its container, 
than S, no data is deleted. If offset+size is greater than S, all 

the data from offset to S is deleted. Neither case produces an — — ^— — — 

gjj^j. 5 void CMDckte\Wue(CMValue value); 



— — ^— — ^— — — " The designated value is deleted from its object property. 

VOID ^iDc6neVaJud)ata(ciaVaiuc vahie. CMSi« ofect, ^ deleted value Will be treated bv aU Container Manager 

Operations as though it does not exist For exan^le, it will 
10 not be found by CMUseValue, counted by CMCountValues, 

Existing data in the container, which must have been in etc. 

the container when it was opened, is defined as the data for If the value deleted is the only one for the property, the 

the value. No data is written to the container. property itself is deleted as in CMDeleteObjectProperty. If 

The designated value is set to reference the indicated Hata that property is the only one for the object, the object is also 

The offset given is the offset from tiie beginning of tiie deleted as in CMEteleteObject Some values are protected 

container. It is an enor to give an offset or a size that would deletion. Protected values include the predefined TOC 

result in the value containing bytes outside of the data that ^^^^^ values (seed and offset) and any currently open 

was in the container when it was opened. The offset embedded container values. 

therefore, must be in the range of 0 to N-1, where N is the 

'^^^l?'^^"^^^^ '° void CMRelcasaVaMCMVW^valu.); 
Additional calls to CMDcfineValucDataQ for the same 



value will define additional, i.e. continued, segments when 
the offset produces noncontiguous data definition. If tiie size association between the Value refnum and the entry 

of the last (most recent) value segment is S, and the offset destroyed. After this call the refhum is invalid, and may 
for that segment is such that offset+S equals the offset for the ^ returned from a subsequent CMUseValuc or 
additional segment, tiien tiie last segment is simply CMNewValue caU to designate another value, 
extended. This foUows tiie same rules as jq- DYNAMIC VALUE HANDLERS 

A. Sample Session Flow 

'^^^^^^'^^T^''^''^'^'''^'^^ Before describing some sample dynamic value handlers, 
^'^'^ it will be useful to have an overview of the session flow 



which might take place for an application program which 

Moves the specified value from its original object prop- uses the Container Manager. 

jty to file specified object proper^. The value is physicaUy pirst, tiie application program would start tiie session by 

deleted from its onginal object/property as if a calling the Container Manager APIs for starting a session. 

CMDeleteValueO were done on it If the value deleted is tiie These APIs, among other tilings, create tiie session global 

only one for the property, the propcaly itsdf is deleted as in (iata block 402 (FIG. 4). 

CXlDdeteObjecffiTOf^^ The appUcation p^og^am tiien calls tiie Container Man- 

The value IS added to die '*to"s object property in tiie same AWc^ ^ia^- tl. JZ^^^^ « ^™tT5« 

« - rT»*xT 1 rr-L .i: t ^ 40 API(s) eitneT to create a new container or to open an 

mann^ as a CMNewValue()^TTie or^^ of tiie values for ^ ^^^^^ j^^^^ ^^^^ containcr^ntrol 

K !f 'JJ^t^"^ object property and for tiie value's ^ ^ ^ ^^^^ 

new object property may be changed. „ ^ ^ ^ ^^^^ uic xxj^ ^x^. 

Note, tiiat altiiough tiie effect of a move is logically a J appUcation program tiien desires to dt^e a type 

combination CMDeleteValueO and CMNewValuc(). tiie whic^ incorporates data transformation and/or redirection, it 

refiium of tiie value remains vaHd. Its association is now .^/^^'^ . Container Manager 

with die new object prcpcrty CMSetMetaHandlerO routine to associate a desired metah- 

niis operation may be done at any time. No data need be ^^obel name of tiie type. If tiie desired type 

associated witii tiie value at tiie time of tiie move. Only ^ subtypes, tiicn tiie appUcation 

moves witiiin tiie same container are aUowed. ^'""^ ^ CMSetMetaHandlcr() for each of ttie 

50 subtypes on the tree which requires a metahandler. These 
calls set up the metahandler symbol table 4*4 (FIG. 4) in tiie 

VOID CMGctValuelQfb(CMValuc value, CMCootainer *CQntainci; memory 304. 

CMObjcct *objoct, CMPropcrty *piupcity, Qnce all required metahandlers have been associated witii 

CMGencratioa 'generation); respective type namcs, the application program regis- 

55 ters the desired type with the Container Manager using 
The container, object, property, and generation of the CMRegisteiT^^). This call creates a type object such as 
designated entry are returned. NULL may be passed for any that shown in FIG. 7, which merely associates the name of 
argument except the first void CMSetValue'iype(CM Wue tiie desired type with a type ID number (tiie object ID of ttie 
value, CMiype type); type object). Again, if tiiis desired type is to be created using 

The type of the value is set as specified. 60 a tree of sub-types, the application program would then call 

CMAddBaseTypeO to add the base types in the sequence 
— ^— — desired. These calls construct the remainder of the type 
c^l^^^^^^*^^^*^*^"*^^"^ object as shown in FIG. 7, as weU as flie separate type 

objects for each of the base types. Note that if a given type 
65 is at a leaf of a type tree, its type object would contain only 
The generation for tiie specified value is set The genera- the type' s global name (in value 706 of global name property 
tion number must be greater than or equal to 1. Normally this 7(W of ttie type). Only if tiie given type has one or more base 
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types do value segments such as 708, 710 exist for a base example, from real value data segment 512), it pcrfonns a 

type property 712 of the type object scries of steps to obtain the data dynamically. First, it calls 

Once the desired type tree is set up for a desired type, the cmGetDynHandlerAddressO with v, with a pointer to the 

appUcation program mayaeate a value in one of its objo^ dynamic value vector 530 entry which should contain the 

for tfie desired type. This is accomphshed by c^ 5 pointer to the read handler for the "compressed file" type, 

CMNewValueO and specifying the object, and the property . """^ ica« u<m«icnui uic wiu^w&w lypc, 

within the object, as weU as the desired type. and with a flag indicating that it is a read handler which is 

CMNewValueO creates a value header such as 506 (FIG. 5) being sought If cmGctPynHandlerAddrcss() finds a non- 

for the new value and places the type ID into that value NULL pointer in the specified entry of dynamic value vector 

header. Assuming the type or any of its subtypes has a •'new 530, it merely returns since the read handler address was 

value" handler and a *Mse value" ^dl^ associated wi& it previously obtained, Othawise, it invokes the metahandler 

by one of the me^^^^^^ identified m the imitahanmer ^ ^ . ^ metahandler was pievi- 

symbol table 404 (HG. 4), the routine then sets up the entire ui*^ ^ypc ^uicpomicr lur wuiui u«;um*mui« wo* previ 

dynamic value chain (e.g. 518, 520, 522 in FIG. 5) fcr the P^<^<^ ^ dynamic value extensions 524 when the 

new value. Note that if the application programmerdy wants dynamic value diain was created), requesting the type* s read 

to use a value which is akeady defined with the desired type, handler. The metahandler returns a pointer to the same, 

it would call CMUseValueQ instead of CMNewValueO to which cmGetDynHandlerAddressO places in the previously 

set up the dynamic value chain. Ndtiier CMNewValueO nor specified entry of dynamic value vector 530. After calling 

CMUseyalue() ac^ally ^ any of the dynamic value cmGetDynHandlerAddressO, CMReadValueData() then 

vectors (e.g. 530, 532, 534 in FIG. 5) at this time, , , 1 u ji : * -1 * u j u ai 

^ \, ** , . . . . . ,ft invokes the handler now pointed to by the read handler entry 

Once the dynamic value cham is set up, the application 20 , ^ ' 

program can caU any of the value operations of the AH as ^^^^^^ ^^""^ 

desired. For example, it can call CMWriteValueDataQ to xhe read handler for the "con4)ressed file" type will be 

write data to the value, or it can call CMReadValueDataQ to very sisnplt since it does no transformations oc redirection, 

read data firom the value , , . AU that work is performed by the base types "conroression" 

Inordatounderstandwhathagpcns whenthcapphcab^^^ 25 .^^ "compressed file" 

program mvokes one of these APT calls, let us assume that r • • 1 ^ 

Ae value has the type shown in FIG. 1 (compressed file type ^^^^^^ ^e: 

102). The dynamic value chain wtiich is set up for this value 

would theref cffe look like the three-level chain 518, 520, 522 ^„ ^ cMGcffla«\Uuc(v); 

(FIG. 5), with tiie top layer 518 having the compressed file 30 letutncdSize » CMReadA^}acIHta(bv, destination buffer, 

type 102, the middle layer 520 having the compression type offset, »izc); 

106, and the bottom layer 522 having the file access t^e — — — — ^— — — 
104. Since the bottom layer type is a data redirection type, 

the information in real value data segment 512 indicates how The CMGetBaseValueQ routine merely checks for errors 

to reach the literal value, rather than the literal value data 35 and then returns the pointer to the supplied value's base 

itself. For example, real value data segment 512 may contain value, which was previously steered in the extensions 524. In 

a file name or a file handle. this case, it will return a pointer to dynamic value header 

When the application program calls CMUseValueQ, that 520. CMGetBaseValueO is implemented in the Container 

routine returns a pointer (called v for the purposes of the Manager as follows: 



@ 1992 ^ple Con^utei; Ibc. 

CMVUue CMJIXEDARGS CMGcfflascVilueCCMYalTje value) 
{ 

TOCValueHdrPtr theValucHdr. 
ContaincrPti cantainen 
Eriff£Bad\Wuc(vahxc, NULL); /* validate value •/ 
H^VahieHar = (TOCVMucHdrPtr)vahifi; 
oontamcr = theWaeildr-ocoDtainer, 

if (contaiiieF^^efBaseVataeOk <^0){I* only callable from a handler */ 
BRRORl(CM_cri_CanlGetBase, CONTAINERNAME); 
returo (NULL); 

} 

if <IIfiDynainicVaIue(value)) /* if not dynamic vahie... */ 

return (NUIi); /• ...dieac is no base */ 
ictum ((CM%lue)DYNEIXIENSIONS(valuc>->base%hK);/* tetum tl» baae valir •/ 



description below) to the top layer dynamic value header Accordingly, the read handla for the "conqaressed file** 

518. If the value were not a dynamic value, then type calls CMReadValueDataQ recursively, this time for 

CMUseValucO would have returned a pointer to the real dynamic value header 520. CMReadValueDataQ again 

value header 506 instead. 60 determines that the value header 520 is a dynamic value 

After obtaining v, the application program can call header, and therefore again calls 

CMReadValueData(v, destination buffer, offeet, size) to per- cmGetDynHandlerAddressO to have a pointer to the read 

form a read operation on the value data. Note here that the handler for the "compressed file" type placed in the read 

plication program need not know that the value is a handler slot of dynamic value vector 532. 

(fynamic value. 65 cmGetDynHandlerAddressO invokes the metahandler for 

CMReadValueDataQ first determines that v is a dynamic the type of value header 520 (whidi is "compression** in this 

value. Therefore, instead of merely returning data (for exanqsle), to obtain that pointer and place it in that slot in 
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dynamic value vector 532. CMReadValueDataO then 
invokes the handler. 

The read handler for tiie "compression** type will be more 
coiiq)licated than the read handler for ^'compressed file**, 
since a transfonnation must be peif ormed. The basic format 
for the handler would be as follows, using a combination of 
C-language code and pseudocode: 



bv = CMGetBaseWueCT); 

zeturnedSize = CMReadValueData(bv, ttvaporzry buffer, offiset, 
size); 

decompress data from temporay buffer into caller's 

desttnatioQ bufifer, 
return 



10 



15 



Once again, CMReadValueDataO has been called 
recursively, this time with the value pointing to dynamic 
value header 522 (tiie base value for dynamic value header 
520). In the same manner as previously described^ 
CMReadValueDataO finds and then invokes the read handler 
for the **file access" type, which is the type of dynamic value 
522. Since the '"file access" type is a data redirection type, 
its read handler might have the following format: 



20 



25 



bv = CMGetBascVaIuc(v); 

xetuniedSize - CMReadV^ueDataCbv, filenaniB, 0, some size 
Dumber); 

obtain data &ccn file desigo^ed by file Dame in filename 

buffer, using caller's offset and size; 
vrite the data into calkr's destinatioQ buffer, 
letuni 



As with the previous read handlers, this read handler 
begins by obtaining its base value by. In the present 
exan^le, the base value points to real value header 506, 
although it would make no difference to the read handler if 
the base value pointed to yet another dynamic value header. 
The read handler then calls CMReadValueDataO using the 
base value, in order to obtain it in a buffer **filename", 
information which tiie read handler will interpret as a file 
name. The read handler then opens the file identified by 
filename, obtains the data from the file, and places the result 
in the caller's destination buffer. 

Jt can be seen that CMReadValueData has now been 
called recursively yet a fourth time, but this time the value 
passed to it is a real value rather than a dynamic value. 
CMReadValueDataO determines this and merely returns the 
data from ^e real value data segment 512. This is the 
information which the read handler for the **file access"* type 
interprets as a file name for use in obtaining the actual data. 
Note that although the data in real value data segment 512 
is not the literal data ultimately sought, as used herein, the 
bottom level read handler is stiU considered to "operate on" 
the data in real value data segment 512. 

Certain optimizations can be implemented in the latto- 
read handler due to the fact a static storage area (refCon) for 
the value is available to it. For example, the read handler 



might be written to follow the above procedure only if this 
is the first time the read handler has been called with respect 
to the particular value, and can save the file handle returned 
by the file open routine in the value's refCon. In all 
subsequent times that the read handler is called the read 
handler can simply use the file handle from tiie value's 
refCon to read the requested data. 

Yet another q>timization can be implemented if the read 
handler knows that it is always the bottom handler on the 
chain. In this case the value's **use value" or "new value" 
handler can open the file using the file name in the value's 
real value segments, and can store the file handle in the 
value's rcfCon. Then the read handler could be written to 
always obtain the file handle from the value's refCon and 
never call CMReadValueDataO to obtain a file name. 

After placing the result in the caller's destination buffer, 
the read handler for the bottom level dynamic value header 
536 then returns to the CMReadValueDataO routine which 
called it, which in turn returns to the read handler for the 
second level dynamic value header 522. That read handler 
processes the results as previously described and returns to 
the CMReadValueDataO routine which called it. That rou- 
tine then returns to the read handler for the top dynamic 
value header 518, which, as previously mentioned, needs to 
do no further work before returning to the 
CMReadValueDataO routine which called it. That routine 
then returns to the caller, which is the application program. 
Hius the application program has obtained the data it 
30 requested, without ever having to know that the data was 
obtained from a file rather than from the real value data 
segment 512, and without ever having to know that the data 
underwent decompression before being returned. 

When the qiplication program finishes its worlc, it calls 
the CMQoseContainerO API routine to close the container. 
Hie routine writes only real value data out to persistent 
storage; dynamic values, including the entire cfynamic value 
chain, are deleted. 

B. Sample Value Handlers 

Appendix A is a header file for a sanq>le set of value 
handlers for a data encryption/decryption type. Hie handlers 
themselves are in Appendix B. Similarly, Appendix C is a 
header file for a sample set of value handlers for an indirect 
file access type. Hie handlers fliemsclves are in Appendix D. 

The foregoing description of preferred embodiments of 
the present invention has been provided for the purposes of 
illustration and description. It is not intended to be exhaus- 
tive or to Umit the invention to the precise forms disclosed. 
Obviously, many modifications and variations will be £^ar- 
ent to practitioners skilled in this art The embodiments were 
chosen and described in order to best explain tiie princ^les 
of the invention and its practical application, thereby 
enabling others skilled in the art to understand the invention 
for various embodiments and with various modifications as 
are suited to the particular use contenq)lated. It is intended 
that the scope of the invention be defined by the following 
claims and their equivalents. 
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/j 

5 j <« ExenpUCryptHandltrs.h »> 

j Exenpte Encrypt ion/Decrypt 1 on Value Handler Package Interfaces 

_ _ j Ira L. Ruben 

10 I 5/11/92 
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Copyrfght 1992 Apple Coopucer, Inc. 
All rights reserved. 



Thfs file contains the fntcrfacea for Cncryption/Oeeryptlon value exwpU of d/ramfc 
value use, See ExaopleCryptHandlers.c for conplete bocuientation on the iBpleaentatfon. 
Uhat IS provfdod here f« all that you would need to use values that encrypt or decrypt 
20 data to and from a base value, see newCryptValueO for further details. 

note, thfs encryption/decryption exaeple offers nn new infomation on how to create 
dimaoiic values. The examples for siiyvalues and indirect fUe pointers do that. The 
main purpose of this exanfile is to provide a dynamic value type that operates on its 
Zb base value. The interesting part fs that we can then use this type AND the file type to 
illustrate nultipla bas« typesi Specifically, » value that does encrypted file I/O. 

Assuning you are familiar with dynamic values by the time you are readino this (if not 
see the subvaluo and file value exaitples). then in order to nakc a crypt/file typa ue 
3 0 want to produce the folUuing type inheritance heirarchy: 



file Type Crypt type 



descriptor Type 



In other words, a "descriptor type" that describes the meanirg, and two base types; a 
encryption/decryption type and a file type, A depth-first traU of the heirarchy produces 
40 File Type at the batton, then Crypt type, and finally, at the top, the Descriptor Type. 

The follovir>9 inheritance Hill equally gork: 

File Type (botton type) 

w 
* 

♦ 

Crypt Type (middle type) 
* 

Descriptor Type (top type) 
With this, the file type is a base type of the crypt type. 

so dynamic value types let yoooix In ther types in different May*. Using a crypt by 
itself is uninteresting, unless of course you want to have all your data values 
encryptedl But the overall alBorithn presented in the cede is very much like the subvatue 
and file value code. 

Using this header, hoirever, you can build the crypt/file type. Assusing you have 
reoistered a descriptor type, deseriptorType, then you can add the base values to it as 
fotlovs: 

65 CMAd*aseTvpe(descriptorType, Reg isterfi I evalueTypa( container)}; 

CHAdcbaseType(d«acriptQrType, ltegiaterCryptVBlueType(canta1ner}); 
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The best ua/ to think of the ordering Is that the base types for any one type dr« 
proctssad in order. Processing includes firet checkins if each of those types has base 
types, and so on. ThU effects the depth-first search. 

5 The ebove tuo CNAdfiaseTypei ) csU« add the file type first and cryyit type second. This 
produces the first type irtierltsnce helrarchy pictured above. 

To prodiKe the second pictured inheritance helrarchy: 

10 cryptType = Reg isterCryptValueType( container) 

CNAdSaseTypcCcryptTrpe, Reg i st erf i I eVa I ueType ( corta i net ) ) ; 
CKAdAaseTypeidescriptorType, cryptTyps); 

Here the file type is nade a base value of the crypt type end the crypt type, now with 
15 its file base type, osede e base type of the descriptor type. 

This second raetbod Is not as general as the first. That's because using a crypt type 
wilt alMys in^ly using the file M a base type. 

20 leaving the types note- or- I ess "atonic* alloHs you to hove mix- in classes (oops, sorry, 
types). So the first method is desired. 

Finally, in all of this discussion, we have been using definitions provided in other 
headers. Specifically the ExaaplelndFI leHandlers.b and ExanpleSubValueKandlers.h. The 
25 RtgisterCryptValuetype is a meera defined in this header. You would, therefore, have to 
include those headers If you wanted to do the above operations. 



30 #ifndef _XCRVPTHM»LeRS_ 
•define _XCRYPTHAI0LERS_ 

# include "cn.Wl .h- 

35 CM^CRJVtCTlOMS 

OWalue CM_FIXEOARGS neuCryptValue(D«bject object, CW>rop*rty proparty, CXType type, 
char CM^PTR *cryptKev); 

/* 

40 This is a special case of oiiieWVatuet) In that a new value entry of the specified type is 
created for the specified object with the specified property. A refllm for this valwe ii 
returned. However, unlike OWeWValueO, the refKiw is associated with a value that 
encrypts or decrypts its data. Whenever the returned refNuD is used for a value 
operation, that operation will encrypt or decrypt of its value appropriately. The 

45 encryption/decryption al^arithni used is a single "exclusive-or- of a key ulth the data. 

The key is passed as a null-tensinated string which is cycllcly used over the data. 
There is no Uait on its length. A null string has the effect of n> encryption or 
decryption. 

50 There is one restriction on this encryption/decryption value leplenentation. Data inserts 

and deletes are NOT supported. This is because the ■exclusive-or" elgorithn depends m 
the data offset in order to know how to use the key. Inserts and deletes affect all 
data that follows. Hence there would be no way to know what part of the key was 
originally used. 

Hote. you would only use newCryptValueO to explicitly create a value with encrypted 

data. This routine is NOT used for layering of base types es discussed above. 

V 

60 

#deftne CryptValueGlobalHamB (OIGlobalNaBje)»'User;CryptVBlue» 

idefine kesisterCryptValueTypeccontatner) \ 

CQISetMetaHandlar(CHGetSes8ien(container), CryptValueGlobalName, \ 
65 cryptOynanicValueftetahandler). \ 

Clfliegi sterType (e onta i ner , Crypt Va lueC I ob« INane ) ) 
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If crypt values are created In a container and then the executing session temlnatcd. the 
indtrtct crypt valuss can bo us«d In 8 future session opening just like nomal values by 
calling CMUseVatueO. The only requlrenent Is that you nust register the crypt base type 
prior to doing the CMUseVstueO. To make this slimier, the above macro is defined. Just 
5 call RegfscerCryptValueTypeO to do the registration. Uote Segist^rCryptValueTypeC) is 
defined 09 an expression nhfch can be assigned to o CMType If you so desire. I his uoutd 
be done to nix the crypt type into sane other coe4)ination of baso types. A rm valua with 
a crypt type ret^ires s single value passed to CM)leWValue{>, I.e., crypUCey. That 
paraoetar is described in ncuCryptValua () above. Thio fact nust be kno«tn when nixing 
10 crypt types with other types to sat the proper CKNewValueO parameters. •/ 



maandlerAddr CH_FI)(EOARCS crypt&yneiBicVBlueHetohendler(CHType target Type, 
Diconst CMGicbalNaoe opera tfonType) ; 
15 /• 

This metahandler is called by the Container Managar for dynamic valm creation to allow 
the Coitainer Manager to get the addresses of the "netsdata", "new value", and *'use 
value" handlers. These handlers are usad as part of the process of creating dynamic 
values. See code for further docunentatlon. 

20 

Mote, the Container Kanager uses the address of this ©etahardler uhen it sees a type 
which has this netahandler registered for it. Registering the metahandler and the type 
can be done with ^e RegisterCryptValueType macro defined above. 
•/ 

25 

CM_EI©_CHJ>iaiO«S 

#end1f 

30 



Attorney Docket No.: APPL: P-1120 MCF/WSW 
wBw/appl/i 12 0.001 142 



12/19/2003, EAST Version: 1.4.1 



77 



5,652,879 



78 



10 



15 



30 



50 



55 



60 



65 



- 143 - 
APPENDIX B 



<« ExaivieCrYptHandlers.c »> | 

I 

Exaii^U Enciyptf on/Dee rypif on Value HandUr P4ek*g« | 

I 

Ira L. Ruben j 
5/11/92 J 



Copyri^t 1992 Apple COifutcr, Inc. 
All rights reserved. 



Ihls rite Illustrates how one misht iafileMnt "special value data maniputatfans** using 
the "dirrMiic value" nechaniuts provided by the Container Haragcr. Dynanric vatucs ire 
special values which **knou" hou to aanipulat* on their oun value data. They do this 
through a set of value operstion handtera uhfch are expected to be semntjcaUy the ssiie 
20 as the standard API value operations. This fs described in onre dotaM later. 

The "Gpeeial value data manipulBtions" dynamic valu« we want to st^port here is for 
sfflple encryption and decryption of value data. All value operattom on the dynamic 
value will then be encrypted or decrypted appropriately. The encryption/ decrypt ton 
25 algoritha we use is a sinple *iexcliisive-or" of a Itey with the data. The key ts cychcly 
used over the data. 



The key Is passed bs a null - terfslnated string. There Is no Hailt on Its length. A null 
string has the effect of no encryption or decryption. 



There is one restriction on this encryption/decryption value tnptenentstion. Data inserts 
and deletes are HOT started. This is because the "exclusive-or" alaoritha depends on 
the data offset in order to know how to use the key. Inserts and deletes affect all 
data that follows. Hence there would bt no uay to know uhat part of the key was 
35 originally used. 

Basically, <tynailc values are similar ro C++ objects where the handlers are the object's 
methods. Dynamic values are a generalized sechanlsin that provides for type Inheritance. 
They ar* similar to C++ objects Oiere the handlers are the object's nethods and an 
40 object' t type represents Its class. They ere dynanic in the sense that they only exist 

Iron creation (discussed below) and last until until they are released (CMReleaseValueO). 

The encryption/decryption eianpla we will jtlustrate here iUustratas the type inharitanca 
where the type of the value has ss its base type, a "crypt« type. As discussed In the 
45 CMpanion header file for this code, the intent Is to define a type idiich can be nixed in 
with other types. In Us most basic use, the -crypt" type would be a base type on a 
descriptor type <i.e., a type which dsscribes what we're kind of encryption this is, or 
Uhatever). In that case all I/O to a value's data would then be encrypted or decrypted 
appropriately. 



By defining the "crypt" operations in terms of its base type, we can use It more generally 
with other types- The example illustrated in the header is for a Mile" type that dots 
J/0 indirectly to a file. So by using both the -crypt" type and the "file" typo, I/O 
could then be encrypted/decrypted to a separate file. 

Follow tho code in this file in the order presented. The conwnts docunent the steps 
retired to support the "crypt" type. The newCryptValueC) routine defines the interface 
that can be used to create a crypt dynanic velue. It would be called Just like any other 
Container Manager API routine. 

Vote, however, as Just stated, you won't need newCryptVatueO except perhaps for the 
^basfc case. For ml*- Ins. you would follow the procedures described in the header file. 
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/* • 

\ DOS (80x86) USERS - USE THE "URfiE" KEMOSY NOOEL UHEM CCMPILED FOIt 80X86 MACHINES | 

5 Th« Container Hanager is buHt Mlih this san» option and asnines aU handler and 

^metahandUr lnt«rf«CQ« ar« sfnflarly built and can be aecssacd «ith "for" pointers. 



yinclude <stddef .h> 
10 ^include <stdUb.h> 
^include <stdio.h> 
«jnclucl« <string.h> 
^include <»td3rs.h> 

15 #ifnd8f _CH API_ 
•include "CfCwi.h" 
«endif 

itUndel _xaiypTMMiiLe8s_ 

« include "ExampleCrypttlondlers.h'' 
20 «endi^ 

CM^CFUMCTIOHS 

/•Sec cannmta in CH_APl_envfranment.h about CH CFLWCTIONS/CH EMO CFUIiCTIOW <U5ed •/ 
25 /* only When CQoplling under C++). ~ ~ •/ 



/♦ In ortfer to makv this code read fr«D the cop down. It is necessary in a few fnstances*/ 
/•to forward raferenca cone mtahandler function*. Due to setae "conplaints" from •/ 
30 /* certain c coapflei*" <who shall remain nawless), the forward declarations are placed •/ 
/• hare, Basically, ignore this stuff, */ 

static CHHandlerAddr cryptValueMetahandUrCCKType targetType, CMcorwt WBlebalHaniB 
cperationType): 



/* CEMERAL HOTE... 

In order to iralte the code as general as possible, the session handlers providad by the 
40 API are used. This includes nwnory allocation, deallocation, error reporter, and 

access to the container Identification. These interfaces allow us to use the sane 
• nenury and error handlers that the Container Hanager uses as provided to 

CMStartSesslonC) through the methandler passed there. Tha container fdontification 

interface allows us to add that information to the error reports. The wording of these 
45 ^ nessaoes follows the "flavor" of those done by the Container Hanager itself. 



/* * 

50 I newcryptValue • create refBun for a value that encrypts/decrypts its value data j 
*••-••---•"--"------- — ........... * 



This is a special case of CHNeWValueO in that a new value entry of the specified type Is 
created for the specified object with tha specified property, A rafNuo for this value is 

55 returned. However, uilike OWerfValueO. the refNun Is associated with a value that 
encrypts or dacrypts its data. Whenever tha returned refHun ia used for a value 
operation, that operation will encrypt or decrypt of Its value appropriately. The 
encryption/decryption algorithm used is a ai^ple •^clus1ve*or<* of a Icey with the data. 
The key is passed as a nuU- terminated string which is cyclicly used over the date. 

bO There ie no limit on its length. A null string has the effect of no encryption or 
decryption. 

The types are the key to generating dynaeiic values. A dynMiic valua rwults when a value 
is created by to OWeWVaLuaO or attenpted to be used by OWseValueC), and the following 
two conditions occur: 

1- Tha type or any of its baa* types (if any, created by CMAddBeselypeO). are for 
global names that have associated oetahandlers registered by CKRegisterTypeO. 
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2. The >et«handlers sunwrt the operatfon type to return a "use value" handler, and 
in KUitfon for OWeuValueO, ••metadata" anJ "nsM value" handlertt. 

"Metadata" handler* are used to define metedsts that ts e foraBt dncrfption that directs 
DtVeuVilueC) on how to interpret it's parameters to produce a data packet of thoie 
poremeters. The data packet is sent to the "new value" handler. In thi« routine we wIU 
do a CHNeuValueC) to create the dynamic value with the newCryptValueO cryptXey as the 
parsMters. 

••New value* handlers are uied to define initt«i1zax)on data for the **U5e value" handlers 
based on the data packets. The ■Hisc value** handlers ere called to set up end retu-n 
refcotts. Another aetahandler address Is also returned from the "use value" handler. This 
is used to get the address of the value operation handlers corresponding to the standard 
15 API value routines. 

The goal is to create ■ dynamic value to return. Which when used uill produce the desired 
crypt. Thus ue need tuo types: 

1, A type that describes the eieantng of this crypt value. That is the type passed to 
this routine. 

i. A base type that represents a "crypt" type In general. The user's type fs jivan the 
"crypt" type bs its base type. 

It is that general "cry^t'' base type that most of this file sif^rts. HanielY the various 
netahandlers and handlers for encrypt and decryption. Indeed, the only thing tie do here 
is set up the types, regtetar their methandlerSj and do the CHNcwValucC). 

30 Note, yeu Mould only use newCryptVolueC > to explicitly create a value with encrypted data. 
This routine fs NOT i^ed for layering of base types as discussed in the header. 
*/ 

CKValue CMJIXEDARGS neuCryptValuecCHObJeet object, Clfproperty property, CHType type. 
35 char CH PTR *eryptl£ey) 

< 

CHContaincr contBtner; 
cnsession sessionOata; 
CHType cryptType; 
40 CHValue dynamlcValue; 

/* Get the container refMwn and session data pointer. They ere needed for registering */ 
/* metahandlers and types and for reporting errors. Hote, If the container is passed */ 
/•as IWLt, the saeeion pointer will end Mp being hull. In that case, tM can't report */ 
45 /* the error and just return «a.L, •/ 

contBiner , = CMEetObjectContainerC object); 
sessiorDatB ■ CNGetSe3Sion(contafner); 

50 if (sessionbata " NULL) /* if no session... */ 

return <NULL); ...there is nothing nuch else we cen da here V 

/* Oo a safety check on the refHtau. .. 

55 if (object NULL tl property - HULL } J type MULL ;| cryptKey MULL) < 

CNErrorCsessiooData. -Hull object, property, type refKua, or key refUixi passed to 
netiCryptValueO"); 
return (WLl); 

) 



60 



f* If you wanted to really be paranoid, you could check that the property and type ♦/ 

/• both belonged tc the same container. But lets be "trusting" for no«! •/ 

f Register the crypt type (or reregister it just to make sure Its registered) and •/ 

/* then define the caetahandltr for that type which wilt return the '^metadata'*, '•neii «/ 
/* value", and "use value" handlers (described later In this file). Kote, the crypt •/ 
/* global name, as welt as the mecahandler are published in the crypt htsder file to V 

r* allow other combinations of base types tftat night want crypt as one of their •/ 
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inherited types. Further, to use th» value we're creatine In the future sessfons, *J 
f* the caUer sinply docs D OftJseValueO. But that requires the type end fts •/ 
/* (mtehandler be registered Just as vd do here. As a convenience ho provide a nacro V 
/* to do this In the header file. For clearfty, we do It ei^Ucltty here. V 

CKSetHetaH3ndler<o(GetSess1on<cantBlner), Crypt Valuedoballisne, 
cryptE>ynB!Dl cVa lueHetahand t e r ) ; 
cryptType » CMResf9ter7ype( container, cryptValuealobalRaine); 
if (cryptType NULl) return <UULL>; 

/* The crypt type will be defined ss a base type for the eaUer's type. The caller's */ 
/* type is already defined, tt is asstned to be a type tfiat describes uhat kind of V 
/* encryption this la. The type helrarthy we want looks soiwthtns like this; *f 

15 . /* Crypt Type (bottoo type) */ 
/* ♦ •/ 

/* * »/ 

/* • */ 

r* Caller's Type <top type) •/ 

t* In other uords^ ue want the crypt type as a base type of the description type. */ 
/* This is easily accomplished as follows: */ 

CHAdtlSaseType(type, cryptType); 

f* Base types are essentially values for a special "base type* property added to the */ 
/* type object. fcbove ue're defining cryptType as a single base type for the type, •/ 

/* That's about all there is to it! Now alt that's left is to do the CHNewVsluet) •/ 
30 /* to create the dynamic value. */ 

. dynaaicValue = CKMsuVa I ue (object, property, type, cryptKey); 

f* The dynenicValue is now created) Ue can return it to the caller. Note that the •/ 
35 (* cryptKey is passed to CMleuValueO. It has no Ides what it is I But it does know */ 

/• hou to deal with it. Specifically, (t pesses it to the '^tadato" and «new value" */ 
h«idlers during the creation of the dynamic value. CWle«Value(> knows there is one */ 

/* additional parameter because of the metadata we return froo the •metadata" handler. V 

/* You can sea it works scoiethir^ like "prlntfO", although across two different */ 
40 /• places. The netadata tcUs OWeMValueO to consune the additional parameter Just •/ 

/• like the "prirtfO" format string telle "printfO", */ 

/* Setting back to the dynanic value to reiterate, the rules for dynnlc value •/ 
/■ creation are that when a OWewValueC) or CNUseValueO are done, if the passed type,*/ 
45 /• or any of its base types have (through associated metahandlers) a *use value" •/ 

/* handler, and additionally for CMNeUValueO, a ometadata" and ••new value" handler, V 
/* 9 dynamic value is created. */ 



25 



50 > 



55 



return (dynamicValue); 



/* That's all there is to it I From this point on we turn our attention to the definition*/ 
/* of the metahandlers and handlers. «/ 



60 / 

I cryptOynanicValueHetahardler - mtahandlBr for crypt dynanic value creation 



The first methandler to be defined Is the metahandler called frew CMMetiValueC) or 
55 CHUseValueO for dynamic value creation. It does this lo see If e type, which had this 
tietahandler registerad for the type global nane, has a "use value" handier, and 
additionally for CKMcwValueo, •vnetadate" and "new value" handlers defined. That is the 
criteria on whether « dynamic value Is to be created. 
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7h» "r»tadata", *'rmt valo»", and "use value" hwxlLera have the folloHfng prototypes: */ 

static cmctaData metaData^HindlertCHrype type); 
5 static CMBoolean neUValue.HftndlerCCNValiw dyruMicfiaMValu*. CUTyps typo. 

OOstaPadcet dataPacJcet); 
static CHBoalean u$eValw.HandUr(CMValuft dyranfcBasaValut. CMType type, 

□WetaHandler •actahandler, CHRefCon *refCon); 

/♦ 

10 "the paraneters are defined later in this f [te in the docmentAtion <or th*se routines. 
*/ 

WHandlerAddr cn.PIXEDARGS cryptoynaaicVa I ueMetahandler (CMType target? ype. 
CMconst CKGloballlanB opera tfonType) 
15 < ~ 

CMType ignored targetType; 

if (3trcflf)((chor *)oper&tfonTYpe, CHDef ir*e«rt«OataOpTypeJ«0) /* "Retadflta" ♦/ 
return ((CHtf4ndlcrAddr}aietaO«ta,HarKlUr); 
20 el»« if (stroi^Ctchar *)operationTYpe, CNHtt^alueOpType) « 0)/' value" */ 

return ((CMK4ndlerAddr}neWV4lue_Handier); 
else (f <strcnp(Cchar *)operat1onType, CHUseValueOpType) 0)/* "use value" •/ 

return ((CHHand(«rAddr)usfV4(ue_(landler); 
«lse ~ /* what's the f^tion7 V 

25 return (HULL); 



/ • 

30 { ii»ttfata_aandler - return the notadata for the crypt type | 

The "Metadata" handler is called fron OWeUValueO so that the profser naber oi its •>..." 
pere»eter8 can be placed into a data packet to be passed to tha -new value" hanllcr. This 
35 handler talces the type for Hhich we ant to return the corresponding mtadata. 

In the case of crypt values, u« want to pass tha ncMCryptVelueO pwaweter that defines 
the encryption key. I.e., the cryptXey. The metadata "Xp" will serve the purpose, it 
specifies a pointer to the key string. 

40 

note, we can define any fonwt we thing is apprepriete for the '"new value" handler so 
long as it uses CMScanOataPacketO to extract the paraaxters ard uses this handler itself 
to get the metadate format string. That's i*iat ws will do when we get to the "new value- 
handler. 
45 V 

static CHNetaOata BietaDats_Handler(CJfType type) 
CMType unused = type; 

^ return ((□•4etaData)«Xp"); f* for the cryptitey pointer •/ 



50 



55 /* • 

{ newVa(ue_HBndler • create peraanent data to for the "use value" handler ! 
* - • 

The "new value" handler is called froei CMMewValueO for dynamic value creation just prior 
60 to calling the *iu5e value" handler, [t is not used bf CHUseValue<), 

"New value" handlers are used to define initial iiatioo date for the "use value** hwidlere. 
It is BssuMd that such data will be some function of the original parameters passed to 
CMMcHValueO. These ore packed into the dataPacket according to the aetadata defined for 
65 the type. If there are nultfple base types, each type's Metadata directs CMMewValueO on 
hoM many of its peraawters to consune in build a data packet. 

Base types are processed fn a depth-first oBnner, so CMMewValueO parweters are 
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eonsifled let t- to- right, for the deepest base type to the highest. For exanple, gfven the 
follwifts type Inheritaneo heirarehy (read these as Tt ir*erit» from T2 and TJ, and so 
on): 

5 T4 75 

TZ T3 
* * 

10 • ♦ 

n 

The depth- first search, starting 8t Tl, ytelds the sequence! T2 T4 T5 r3 T1. Then this 
is the order the OWeWValueC) parameters must be \n. It is also the order the 

15 dynsnfe value lerers are generated. Tl is the top layer, and T2 the bottan. T1 would be 
the dynanfe value returned from CKNtuValueO. 

[n this axanfile we only have a single base type, the "crypt" type, »*ich has metadata 
defined to pass a pointer to the emryptlon key string. 

20 

Fran this data ue «ant to write permanent Information so that the "use value" handler, 
Mhleh is always called for CHHeuValueO end CKUseVatued, can create en appropriate rrfCon 
to pass among the value operation handlers. Tht date Uyout chosen is as foUous: */ 

25 stnict CryptData < /* Enerypt/docrypt data layout: •/ 

unslsned long keysize; /* size of the encryptlon/dKryptlon key •/ 

Uttlgned char thsKtytn; /• encrypt f on/decryption key starts here */ 

>; 

typedaf struct CryptData CryptData, •CryptOataPtr; 

30 

/• 

In the above data, we only have to remenber the encryption Ice/ and fts size <the reason 
for the size will be explained shortly).,. This Is the deta Me mIU write to the dynenic 
value's basa value. It is thus permanently remobered. Mow, if the centainer is opened 
35 for reading, if a CKUseValueO Is done on the value, the <Mse value" handler will read 

the data just as in the CMMeuVaLueO case, ftenentier that newCryptValueO is done only to 
initially create the crypt value. Future uses don't caU ft. So nothing should be 
written that can't be used by only ealUng "use value" handler without its "new value- 
handler. 

40 

In this particular exaeple, whe have a "security leak>M Ue are writing the key to the 
base value. If that base value fs a real container value, then we are writing the key 
into the container. As an example, we're not goins to get to picky here. We're net 
trying to stop the CIAI So we will leave It at that. 

45 

For what It's worth, if the base value Is HOT a real value, but a dynaifc value that 
is at a lower level In the base type inheritance chain, then we're writing tfie key to 
the dynamic value. It nay choose to dispose of it any way it sees fit. 

50 Take, for exanplc, the "file" base type that writes to a file Instead of the container 
(done in ExaeplelndFileHandlers.thc] end discussed in the header for this file). Then 
ue will be writing the key to the file and not the container. The file base type 
hi^lights why we save the Icey size as pare of the date. The key Is variable length. 
But you would think that the »use value- handler could do a CHGetValtieSizeO on the 

55 dynanic base value. In this file case you would end 141 getting the size of the f ilel 
The key is in there at the beginnins of the file. But we would not know its ler^th. 
Hence the safest (only) thing to do Is explicitly write the size. This will mean that 
the "use value" handler will have to do two reads; first for the size end then for the 
key. But that's life! 

60 

Ue don't know our context here. Nor should we I Ua only knew we're writing special date 
to the base value. Since we also do all our value handler operations to the base value 
we nust take into account the data we have urftten. In particular, the user of the 
value we return from here doesn't know we wrote this data- So a user will always think 
55 of the data s/he reads or writes starts at offset 0. In reality it will be offset by the 
Size of the data ue write. Our handlers oust take this Into accoint. 

This will generally be true of all generic type dynamic values that do all their 
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operations on only their bas« valuts. The subvsliie exMple did its operations on an 
■xi&tir^ velM. Th« file exaripl« does its operstfons to an external file. Here ue have 
a "true" atonic base type thet uses only its base value. Its the nain distinction of 
thie i 



On finot point, if any errors ere reported, we abort the execution of the program in this 
exaaple. As dociMented, error rtf>orter« art not supposed to return. But in case they 
do, the Container Manager wants to knw about iti The OWooleen fmction result is used 
for that purpose. Nonzero should be returned for success, and If this should happen to 
10 return for a failure, 0 should be returned as the function result. 
V 

static OWoolewi newValue_HBndler(CKValuc dynamlcBsstValue, CNType type, 
OtOataPacket dataPacket) 

15 i 

CMContainer container ■ CHGetObJectCont&iner(type); 
CMSesslon sesslorOata = CMGetSe5sion( container); 
unsisncd char *cryptiCey; 
CNCount i: 
20 unsigned Ions fceySize; 

/* scan the dataPacket to put its data back into variables. The API provides */ 

/* mscarCataPackstO to do that. Ue reverse what QWeuValueO did by using our own */ 

/* "metadata" handler to get the netadata to direct the extraction of dataPacket ♦/ 

25 /* fields back to variebles (sort of like a *'scanf(>"}. «/ 

t * CMScanOataPaclcet(type, metaOata^Handlerftype), dataPacket, tcryptKey); 

30 if <i U 1) < 

CHError(sess(orData, •'Unable to get all of CHNeWalueO's \"...\« cryptKey parameter in 
container \"*0\"», CMRetumContQinerNaneCOtGetObJeetConteinerCtype})); 
return CO); 

/• Vrite the encryption key that the "use value" handler will to build its refCon. As */ 
/* disc Used above. u» write the size of the key wid then the key itself. Ue'rc goingV 
/* to cheat a lltcte here and urfte the two values separately Just like the >Hj5e V 
/* value" handlsr uitl read thea, Ue nevtr really use the CryptDate struct above. V 

keysise - strlen((char •)crypt)Cay); 



CMfriteValueOBta(dynaiiicSsseValije, CCWtDSkeySf u. 0, sizeof(uisfoned long)); 

CMfriteValua0ata(dynan1c8aseValua, CCMPtDcryptKey, si zcof( unsigned long), 
45 ccmiiokcyslre); 

return <1); /♦ that's all there i* to do here) 



/ - 

I useValue.Bandler - create a dynanic value and its associated iwtahandler 



55 The »ust value« handler ic called for both OWet^alueO and CmiseValue(). For 

owcuvalueo, it is called after the "new value" handler. Either «ay, the "use value" 
handler is expected to build a refCen to pass uaong its value operation handlers, and 
to return a pointer to the metahandler that ulll yield the aeUresses of those handlers. 

60 Generally, the refCan is built froa the data urittsn to a dynanic vaLuM base wiue by 
the '^r^eM value" handler. That data is pernanent, and thus a CMUseValueO on the value 
of the dynaiite value type will cause the creation of the dynamic value even when the 
••new value" handler is not called (as Is the case for oWseValueO). 

65 AS with tiie "new value" handler, the type Is passad as a convenience. It nay or may not 
be needed, for the "new value" handler it is passed to CllScof*BtaPBcket( ) to convert 
the data packet back into variables. Here, it iwy not be raeckd. it is posiibLe for a 
type object to contain OTHER data for other properties. Types, alter all. are ordinary 
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objects. There Is nothing prohfbtttng the creatfon of tddftional propertfes and their 
value*. This fact could bo used to poss additional Catatic?) Infonwtion to the "new 
value" or *M$e value" hanOlera uhlch uoutd read the data values. 

In this exanpte. the «nau value" handler data urftCen to the base value is a« defined by 
the CryptValueOataPtP typedef defined in the '*nw value" handler. It Is just the 
original encryption Itey and its »1ie. 

Tbe refCon Me but Id fron this data has the following layout: •i 



struct CryptRtfCon < /* Cpypt value handler' a refCont */ 

CMStsslon sessfcrOata; /♦ ptr to the current container sesaion */ 

msisned long dataOffset; /• amount to offset user's offsets */ 

iiisigned long keySize; /* size of the encryption/decryption kty */ 

15 ^ WTsigned char theKeytll; /* encryption/decryption key starts here*/ 

typedef struct cryptRefCon CryptRefton, *CryptilefConPtr; /« 

The current session data pointer, which we need to allocate the refCon fs kept Just as a 
20 convenience in case Me need it again. At Che very least It ulU be needed to free the 
refCon. 

As discussed In the "use value" handler all operations are to the base value. Henee, the 
data that the **neu value" handler wrote Is In there. So ve aust offset the user's offsets 
25 to the value operations by the anoint of the data we wrote and s/he has no Iwniledge of. 
Hence the dataOffset field fn the refCon. 

The retcon is accessable to all the handler routines via a CKGetValueRefConC) call. The 
keySiie is the size of the encryption key. The »nvt value" handler reaoved the denialttng 
30 null uhen it wrote the data. Ue donM need ft. 

Mote, ofi with th» "new value" handler, if any errors are reported, we abort the execution 
of the prograa In this example. As documented, error reporters are not supposed to return. 
But in ease they do, the Container Manager wants to know about iti The CKBoolean function 
35 result is used for that purpose. Menzero should be returned for success, and ff thfc 
should happen to return for a failure, 0 should be returned as the function result. 
•/ 

static CNBoolcan u$eValue_Handler<CMVelue dynaoieSaseValua, CHType type, 
40 ^ cmetaHandler *wtahandler, CHRefCon 'refCon) 

CMContafner container » CHGetObJ»ctContainer(type); 
CHSession sessiorOata «• CMGetSession(container); 

(sislsned long keySite; 
45 CryptftefConPtr myRefCon; 

/* since the key can be any siie, tie nust get Its size before we can allocate our •/ 
/• refUin. The size is the first long fn the dynamicSaseyalua's data. */ 

50 if CCMteadl/sluftOata(dynamfe8as«Valua, (CKPtr)£keySizo, 0, aizeof (unsigned long» !> 

sizeof(vnstgned long}) < 

CKError(sessf«rOata, "Incorrect byte length reed while reading encryption key size in 
container \"*0V", CHReturnContafnerilaae(cont«iner)); 

return (0); 

55 > 

/* Allocate the refCon that we will pass among the handlers. Since we are doing a */ 
A* dynamic allocation Here we will use the "ma I lac" handler defined for the container.*/ 

60 mysefcon = ( cryptRefconPtrjDWa I VocCsfzeof (CryptRefCon) ♦ keySize, sessiorOata); 

if (nyRefCon ~ IWLl) C 
CMCrrorCsesslorOata, "Cannot allocate space for file encryption handler refcon in 
containw xo^oxnu, CH(leturnConteinerll«ne(contafn«r)); 
retum (0); 

65 J 

DyRefCon->&essiorCata = sessiorOata; /• save current session pointer V 
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/* Read the kty directly into our allocated refUuni and mv» th« k«y sin... •/ 

inyRefC0n'>)ceyS{ze a kvvSixe; /« sav« k«y six* */ 

5 if (CHReadValutOata(dynanilcBaBoValue, (CHPtr)ir[)4te^Cco*>tb«)Cey, aizeofdjiaigrwd lorw), 

CCTSlje)kevSlze) |= IceySUe) C 

CMErrortaessloTData, "Incorrect byte length read uhUe rewiina encryption key in 
container \*'*0\"", CIWeturrCootainer«a»e(corrtairTer)); 
CKFreeCmyRefCon, sessiorData); 
10 return (0); 

> 



15 



20 



25 



30 



60 



/* Set the dataOffset field of the refCon witb the auwt of data ue read in both th* *^ 
/• above reads... 

wyHefCon-xlataOffset « «ireof<insi9ned long) * keySfze; 

AU that's left to do here is to return the refCon and the pointer to the value 
/* operations netahandUr to the Container Hanager who called us... 

*«ttahandUr - (OfletaHandlcrJcryptValueHetohondUrj/* return metahandler 
•refCon « (OWefConJoyRefCon; /♦ ...and refCon 

return <1); /* wa'ra now ready to a« 



* 

j cryptYalueMetahandler - oetahandler for a dynamic value handler set j 
• ..... 

This is ths mtahandler thai the «use value" handler returns to the Contairwr Hanager. 
It defines the addresses for all the value operations hendlera aupported for files. 

35 Th« dynwiic value operations hsndlers beve the foltowino prototypes: */ 

•tatic CnSize 9etValueSize_Httntflcr{CHVBlue value); 

static CRSize readValoeOata_Handler(CHValt» value, OlPtr buffer, CHCount offset, OtSize 
nox£ize}; 

40 Static void *(riteValueOata_«andl«r<WValue value, CXPtr buffer. CWiwt offset, CKSiic 
size); 

static void insertValueOata_Handl©r(OtValue value, OlPtr buffer, CKCouit offset, CMSize 
size); 

static void deletaValueOata_Handler<CKVa(ue value, CKCouit offset, CHStze size); 
45 static void getValuelnfo_Handler(CHValue value, CMContainer *ccntainer, OWbject •object, 

CWroperty *property, CMType *type, 
CMtentratioo *s«n«ration); 
static void setValueType Handler (CUValue value, CWType type); 
static void setValueCeneraTion_Handler(CHV«lue value, CHCeneration generation); 
50 sutic void releaseValue_Handler(CiiiValue value); 

/* 

Note that these handlers have exactly the sane calling conventions as the standard API 
routines. These handlers must also have the save sonantics. Uhat happens is that every 
time a dynaaiic value is passed to the Container Hanager, (t is validated and then checked 
!>b to sec if it is indeed a dymmic value. If it is, the correspwiding handler ts called to 
do the imrk. 



The actual handler called for the dynaaic value nay or nay NOT be associated uicli the 
type associated irtth the dynamic value. Just like Cf+, dymaic values nay be "subctaased" 
vie their (base) types. If a handler for a particular operation is not defined tor a 
value, its "base value" ts used to set the "inherited" hardier. This continues up a 
dynamic value's chain of base values, qo to the original "real" value that spawned the 
base values frooi the CKUeuValu»<) or OOiseValueO. 

65 In this exanple ua had two types, the "crypt" base type and its base value type, i.e. the 
one passed to neucryptvalueO. The dyrwmtc value returned from there vas for the crypt 
*rff- ^ w* don't supply a value handler for a particular operaticm, the operation 
will end 14) be done to the base value. 
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Taking sdvanttg* o1 thtc cwen* you don't h«ve to supply a handler untes* it {« absotutety 
necessary. Ttits nfntaftes the coding, not to mefitlon code Bi'zel Ue actually do taka 
advantage of the method Cer, excuse ae, value operetfon) inheritance here. Alt value 
5 operoctons iMch do not involve encryption, decryptitfi, or data off«et« <ratrwri>er we 
MTote our own data to the base value) are not defined Ci.«.» »« retum MULL for their 
adcfc-ess) as handlers. 

The "sotValuaTvpQV'BatValuoCfnsration" bandUfs are such handlers. It should be pointed 
10 out that tf the type Is cbanaed* you are xpuUtng** the rug out" iron mder the dynamic 
value creation. Onca released, the value will not have a crypt base type, unless, of 
course, the new type had one. 

Note that we actually declare all the value operations handlers as •static" since they 
15 only need to be vtafblc fn this file. The Container Manager gets at titen through the 
addresses we return from here. 

The handlers do their idork by calls back to the Container Henager. But the values passed 
back cemot be the dynamic value passed In. This could lead to t recursive arvJ endless 
20 loop. This IS detected by the Container Manager aa en error condition. 

In cur crypt case, the handlera will use the refcon to do their respective operations on 
the base value which ue set fron the passed value by cbing a CH6eteaseVslue< > on it, 

25 By the tine a dynaoic value operation handler has been called, all validation checks have 
been dona on the dynanic value by the Container Manager. So they need not be done every 
tine here. Vstidstfon checks include eueh things as the Container Manager being 
Initialized, non-KULL value pointers, etc. In short, all the validations the valua 

30 ^ ^of" nonnBl values before discovering it should call a dynmnlc value handler. 

static CHHandlerAddr eryptValusHetahandlerCOnype tarsetlypa, CHconst OIGlobolNaire 
operatianfype) 

35 static char *operatlonTypesa • {C»iCetV8lueSizeCfc)Type, /• 0 •/ /• operation Types */ 

CMReadValueOataOpType, /* 1 V 
CMWriteValueDat«QpType, J* 2 */ 
CHlnsertValueOataOpType, /* 3 */ 
^ _ CHDeleteValuetataOpType, /* 4 •/ 

40 CMCetValuelnfoopTypQ, /* 5 V 

CHSetValueTypeOplype, /• 6 V 
CHSetValueaenOpType, /* 7 "/ 
CKReleBseValueOpType, /* 8 */ 
NULL); 

45 chap **t; 

CHiype ignored 3 targettype; 

/• Lode 14] the operation type in the operationTw>« table above... */ 

50 t = operationTypos - If 

Mhile (*i+t) if Cstrcnp((char ♦)operationType, •« « 0) break; 

/* Rou that Me got it (hopefully), return the appropriate routine address... •/ 

55 switch (t • operotlonTypcs) { 

return «CHHandlerAddr)getValueSize_wandler); /* CHBetvaluelnfoOpType •/ 
return <(CHNwvtUrAddr)readV«lueOjta_()3ndler}; /* CMReadValueOateOpType */ 
retum <<CKtjBndterAddr)NrtteV8lueOata_Kandler); /* CKWriteValueOataOpType */ 
retum ((OUIandterAddrJinsertValueOato Handler);/* OdnsertVatucOataOpType*/ 
retum (tcnHandlerAddr;deleteValueData"Handler);/* CHDeleteValueOataOpType*/ 
return (MULL);/* use inherited handler or API •//* CKGetValuelnfot^Type •/ 
return (HULL);/* use inherited handler or API *//* CKSetValutTypeOptype •/ 
retum (HULL>;/* use inherited handler or API •//* CttSetValueGcnOpType •/ 
return ((CKHandlerAddr)releaseValue_Handler); /* ORaleaseValueOpType */ 
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f* Since all that's Left are tha value operations thet do encrypting and decryptir^, h* «/ 
/• need a private routine to <Jo the encryption/decryption uork... 

r * 

j Encrypt/Decrypt Data | 



This routine takes data, coiuistinB of dstaSize bytes, end encrypts or decrypts it using 
the key, Iceysize bytes. The slsorlthn does s siiifile '•excluslve*or«' of the key with the 
data. So encryption and decryption are the same. Which way it happens depends on whether 
15 the ^all Is for reading ar wrfting. 

Mate, the key is cycLicly used over the data. As such nhieh key character used daper>ds 
on the offset of each data character. Therefore the starting offset for the data is 
passed. 

This iaplenentaticn only makes sense if no data Is inserted or deleted once encrypted. 
^Hence, inserts and deletes are not supported in this exanpte inpleiaentation, 

25 static void CH_HEAR crypt(Ltf\signed char •data, wigned Ions dataSiie, 
unsigned char *key, unsigned long keySiie, 
unsigned long offset) 

( 

unsigned char *keyStart = key; 



40 > 
> 



45 /*. 



^^If (keyStle = 0) return; /• no key news no encryption 

key (offset X keySIze); /* starting key char is a tuictton of offset*/ 

nhile (dates ire--) < /* process each character of the data... */ 

♦data*+ *= •key«^; /* ,..encrypt/(*ecrypt it */ 

if (+*off8et X keysize « 0> /*.. ,1f MB exhausted the key. . . •/ 

Itey = keyStart; /• ... cycle it •/ 



/* What follows noy are the IndtvlAjal dynamic value operations handlers whose addresses*/ 
/* ue raturned from the above metahandler. As stated above, these routims MUST have */ 
/* the sane scnantics (witJitn reason) as the correspondit^ API routine that calls them, V 
/* If a routine doesn't nake sense for the dyramic value it should report an error. •/ 

r All vsLidation has already been done by the time a handler routine is called. Except •/ 
/• for validation, the Ap[ routine that calls the handler does WTBIMQ else. Note, •/ 
/• however, that eince there is a one-to-one mappfng between the hareJlers a«i their •/ 

5b /• corresponding API routine*, iiany handlers end doing a call back to the Container •/ 
/• Manager to do their tasks possing the paremetera unaltered (e.g., buffer pointers, ♦/ 
/• sues, atO. The Container NanegM- always trys to vetfdate its paraMetars as best V 
/• it can. For exaaple, a WLL buffer pointer is processed ^i»ropriately. What all */ 
/• this neans is that the handlers do not need to do these vaUations either on the */ 

bO /• paraeaters. tt can be left to the Container Kanager if the parmeters are passed (n */ 
/* a coll back. *y 

/• What each of these handlers must do first, usually, is get the refCon ue built in */ 

/* the "use value- handler. The refCon contains the encryption key and key size, V 

6 5 /• ReneiiMr, we have to adjust all passtd offsets br the keysize sinie we wrote the key */ 

/• to the base value (in the «new velue" handler) but the caller doesn't know that. V 
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/ 

j getV«lueSiM_Hainiler - WCetValueStzeO (Jynamlc value haidler [ 
* — — — — . « 

Th» charactar size of the fUe is retumtd. 

Ue nut adjust th« size by the size of our oun data. The user ts not avare of that stuff. 
Ue do simdar offset erithrotic in the h»«ll»ra that involve off s«tft. 
V 

static CKSize getValueSlze HondlerCCHValue value) 
< 

cryptRefconPtr refcon » (Cr^tRefCofiPtr)CHaetValije«efCon(valuB); 



15 ^ return (CMGetValueSize(CNGetBaseValtM(value)) • rafConodatadfffist); 



/• • 

; readyolueDBta,Handl«r • CMReadvalueOataC) dyrwraic value handler j 
* . — — .* 



The encrypted data, starting at the offset, for the value Is read and decrypted into the 
buffer. The size of the data read is raturnwi. \jp to naxSize characters ulll be read 
2o (can be 0), 

The data is read starting at the offset, up to the end of tho data, or naxSize diaracters, 
Mhichaver ccntes first. Offsets are relative to 0, where 0 is the first byte of the 
file. If the starting oftaet Is greater than or equal to the current data size, no data 
ic read end 0 returned, 

static CMSiie readValueDataJandler(CltValua value, CHPtr buffer, CMCouit offset, CMSize 
mexSize) 
35 C 

CryptRefconPtr refCon e <CryptRcfConPtr)CRaetV8lueRefConCvalue); 
CHSiza anauntRaad; 



/* Read the data and decrypt it... */ 

amantRead • cmeadValiKData(CHGetBB»>Vslue(v9lue), buffer, refcon->dataOff aet + Offset, 
naxSize); 



cryptCCunsfgnad char *)buffar, (wsigmd ton9>eiBOuntRead, 
4b refCon'>thelCey, refCon->lceyslze, (mslgned long)offset); 



return (anountRead); 

> 



/• * 

I witeValueOata.Handler - c»»yrfteValueDat8() dynanic value handler [ 



55 The buffer is «nerypted and kritten to the container and defined as the date for the 

value. If the value a I reed/ has data associated uith it, the buffer ovemrite* the "old" 
data sUrtins ot the offset character position, size bytes are written. 

If the current size of the value data is T, then ttie offset may be any value from 0 to 
00 T. That is, existing data aay be overwritten or the value extended with new data. The 
value of T can be gotten using cmi«valueslie(). note, no "holes" can be created An 
offset camot be sraater than T. 
*/ 

65 static void MriteValoeOata.HandlerCCKValue value, CMPtr buffer, CUCoiAt offset. CHSiae 
size) 
t 

CryptRefconPtr refCon = (CryptRefCorf>tr)c:nGetvalueilercon( value); 
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0*Container container « OlGetV* lueContainer( value) ; 
unstyied char *cryptButfer; 

/* Ve wtat encrypt the passed buffer before sending it to the base v«Iim for writing. •/ 
/* It is possible that tho Iwffer passed to us here is a stuple itring constant. AMSI */ 
(* does NOT specify where string constants are ptaced. They could b* in the cod*. •/ 
/* Since code se^nts na/ be execute only and not peniiit siodifi cation, we ntsC copy •/ 
/* the strino to a toes I buffer and encrypt that, IFor uhat it's worth, the RS/6000 •/ 
/* showed this protected behavior.] »^ 

if (siie " 0) return; /* nothinfl to do if no data to uritt V 

cryptBuffer = (tnsltred char *)Oflalloc(8ize, refCon->se»iort)ata}; 
if (cryptBuffer ■» MUti) { 
C»Error(refCon->3essionD«ta, "Unable to allocate output mcryption buffer in container 

0« e tumConta i n*rNaiiw( conta i ner ) ) ; 

return; 

> 

»e«icpy(Cchar •jcryptBuffer, (char *)buffer, (size_t)size); 

/• Encrypt the data in the local buffer and wrfte It, After that He can free the */ 
/* buffer. 

crypt (cryptBuffer, (unsigned lon9)aUe» refCon->theKey, refCon->lieySi£c. (unsigned 
tong)offsct); 

CWriteValueDBtB<OiGetBaseValue(vatue), cryptBuffer, refCon->dataOf fset ♦ offset, size); 
Oifree(CCHPtr) cryptBuffer, refCon->sts£ioH}at»); 



3 5 /* 

I insertValueOata_llandl cr - CMlnsertvalueDataO dynamic value hawller ; 
— — . ^ .* 

The buffer is encrypted end inserted into the value's data at the specified offset, size 

40 bytes are inserted. 

If the current size of the value data is T, then the of feet My be any value frow 0 to 
T. That is, the insertion nay be anywhere within the data value or the value extended 
jnth new data. Th. value of T can be sotton using CHSetValueSizeO. Note, no "holes" cen 

41 be created. An offset cannot ba greater than T. Also, note, that an irwerticn at 
offset I is identical to a CHWritcVolutCataC) to the same place. 

Note this routine is not si^rted for crypt values. See crypt() coments for further 
detai Is. 
50 V 

static void tnsertValueOata_Handler(OiValue value, OfPtr buffer, OiCcxeit offs.t, CMSize 
size) 

55 CryptBefConPtr refCon - CCryptRefConPtr)CHGetValueRefCon(yalue); 

carcount unusedl » offset; 

CHSize unusedZ » size; 

MPtr unus«d3 « buffer; 



60 



65 



OI£rror(pefCon->s»ssiorData. "Insertions into encrypted data for container >»*0\" are not 
si^ported" , 

^ CHRetumC«ntatnerNanie((a(6«tValueContaf ner<value) ) ) ; 

/* * 

I dclateValueOata.Handler - MDeUteValutDataO dynamic value handler 1 
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Oelttes sfzt bytes fron th» v«lu» data starting at tha offatt. If the offset is jreatBr 
than the value data alio, nothing Is deleted. Tha anount to delete nay be greater than 
. the current data afie. In that case, all the data start irg from the offset hUI be 
b deleted. If All the data ts deleted, the value Is defined as null, i.e. a data length of 

IJota, this routfne ia not supported fcr crypt values. See crypt () eanaenis for further 
oetalls. 
10 V 

static void deleteVBlutOata.HandlerccMValue value, CHCoutt offset, OUSixo slxa) 

crvptRafcoTPtr refCon = (Cryptf)efConPtr>CMGetValuea«fCcn( value); 
15 CHCount unusedl « offset;. 

CNSUe unusedZ <* size; 

CHError<refCon->se98tor*at8, i^)* lotions of tncrypted date for container \"*0\* ore not 
supported*, 

20 CMRetumContafn«rNaiw(aiCatVatuaContsiner(value))>: 



25 /• 

\ setValuelnfo_Handler - CHSetValuelnfoC) dyrwnic value handler I 

The apeclffed fnfornation for tht refMun asscciated with en value is returned. A 
30 parameter nay be nuii Indf eating that info is not needed. 

since no encryption or decryption is involved, m actually ust the inherited routine. 
eryptValueMetohendlerO returned NUll for this hwidler Indicaifng It Isn't used for this 
dynamic value. We do show what It would <io if it were really colled. 

J 5 

static void getWalueinfo_Handler(CMV8lue value, CMContainer -container, CHObject •object, 
CMProperty ^proptrty, CKType *type, 
. - OtGeneration ^^ganeration) 

40 < 

^ CMGetValuelnfoCCMGetBaseValucCvalue), cmtainer, object, property, type, generotion); 

45 /• * 

I setVolueType^Handler - CHSetValueTypel ) dynamic value handler [ 
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The type ID froo the type fs aet for the specified value. 

Since no encryption or decryption (s involved, we actually use the irtfierfted routine 
cryptValurtetahandUrO returned MULL for this handler irKitcattna it isn't used for this 
^dynanic value. Ue do show uhat it would do if it were really called. 

static void satValueType_Handler(CHValue value, CHType type) 
CMSetVelueTypoCCKSetBoseVotueCvalue), type); 



• 

j setValueGeneraticn_HBndler - CKSatVslue&enerationo dynwic volue hareiler ; 
. — — ... ft 

The generation for the spedtfied subvalue is set. The generation mriber trust be grwit.r 
than or equal to 1. 
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since no encryption or tfecryptlon is Involved, ue sctuaUy usa the Inherited routine. 
cryptValucH«tah«ndl«r() returned NUU for this handler indicsting It isn't lued for this 
dyiwoic value. Ue do show Mtist ft would do if ft were realty called. 
♦/ 

static void ietVatue<lenerationJanctler(CMValue value, CTGenenBtioo generation) 
^ CHSetValueQeneratfon(0(6eTBa5eValueCvalue). gtneration); 

/• 

I releaseVBlueJandler - CMReteaseVatueO rfynanlc value hanllcr | 

*- — — . — 

The association between the re-fttm and the indirect file dynemic value is destroyed. 
There should be m further operations on the value once this routine is called. This 
handler is only called if this is the LAST use of the dynamic value. 

Acowit is kept by the Container Hanager of every CHUscValucC) and OMewValueC}. Calling 
CMteleascVatueO reduces this count by one. Uhen the last release is done on the dynaaic 
value, this handler will be called. 

Note, in the context of these crypt values, the only thina to do here free the refCon 
memarf, 

Usminjl It is an error for the release handler to release its passed base value. It can 
free any other values, just not its base. The reason is that the Container Marmger is 
30 ^J"P°™'''1< ^or calling the release handlers for alt base types. 

static void releaseValue Handler (CMValoe value) 

C 

CryptRefConPtr refCon - tCryptRef ConPtr)C«GetVaioeRefCoo( value) ; 
3 3 PtSession sessiorfiata = refCon- >sessionData; 

OtFree( refCon, sessiorOata); /• irt* our refCon *> 
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APPENDIX C 



I 



<« ExanplelndFileHandlert.h »> 

{ Exsnple Indirect Ffle Dynamic Value Handler Package tntsrfscw 

I Ira L. It(^ 

4/4/92 

Copyright 1992 Apple Cooputer, Inc. 
I All rlshts reserved, 

I 



This fUe contairw th« fnterface* tor Indirect file value exenple o1 dynamic value use. 
Se« Exanv3leIndFU«Handlar8.c for eonpUte docuoentstion on the inplenentatfon. Uhat is 
provided here is all that you uouLd need to use indirect file values. See 
nwIndirectFileValueO for further details. 
20 V 



#ifndef _XIKt>FILE«ANDLERS_ 
#de<ine _XINDFtLE«AMOLERS_ 

#inclijda "CMJlPl.h" 

CH_CFUHCTIONS 



30 CMVelue CM^FtKEOARCS ncMlndircctFi leValue<CHObject object, CKProperty property, 

CMType type, 

char CH_PTlt *patKna(ne, cUar CM_PlR "oode); 

This is a special case of CNKewValueo in that a new value entry of the specified type is 
3b created for the specified object with the specified prcperty. A refWtn for this value is 

returned. However, irkllke CHNetfValueC], the refKun is associated with an value whose data 
<file) fs indirectly pointed to by a pathnwne. Uhenever the returned refKiis Is used tor 
a valuB operation, that operation will take place on the file pointed to by the pathnaae. 

40 The specified ffle is opened according to the open mode. This nay have any one of the 

the foUouing values: 

"r", "rb" open the file tor reading 
"r*", "rb*" open the file for updating 
45 "***■'*, "Mb*-" trtrcBte or create file and op«i for updating (reading/writing) 

The "b" is always implied if it is not explicitly specified. If a write mode ("w") ia 
specified with a the fs ass wed. 

50 Mote, ff the file is opened for writing <••*»•'>, then all future uses of the value, i.e. 

via CNUseValueC) wfU inply vfxlate mode <"rb*">. Further, dynamic value operations do 
both reads and writes ot their data. Since e file type may be a base type of sme other 
type, update mode is always assuned ('^lb4-'*). 

55 If a file is opened for reading, then a CMUaeValueO nIU open preserve the open status 

and open for reading only. sinUarly, njdate node is pres«rved. The write is the only 
exception. This is because there is no way (fn this exairple at least) to tell 
OlUseValueC) a change in open ntoda. Sorryl It bothers ne tool 

60 The indirect value we want to ti^jport here is for data "pointed to" by a file pathname 

All value operations on the indirect value witt then be to the file. 

Note, luUIpte Indirections are peraJttedl That fs the data pointed to by an indirect 
value night be for another indirect value. 

There is one restriction on this indirect value infilenientatlon. That Is that data inserts 
and deletes are HOT supported. File indirections are cufported using standard C strem 
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s 

tWtfin. flleVlueClobalKa*. tC«Clob.Ui^).w.FUcV«Lue.. /* fll. gUbal nw* (type) V 
Meftne ReglsterFUeValufrTypeCcontainer) \ 

meValueGlehalw^., H I •OynairicV«tueMtt .handler), \ 
^CHReg)sterType(cont8fner, Fi leV«iueGlob*l*l*w)) 



30 



CIIHindln-Addr oi_FIMOAM:s fileOynarieValuetetahandlertcmyw tarc.tTy» 
^ CKconst.CHGlobalHaK opwKionljp.); MrsetTyp., 

45 C«_EirD_Cfl*CTIO«S 
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<« ExartplelndFtUHwidUre.e >» 
Exaople Indirect File Dynaifc VaIim NandLer Pfickase 
Ira L. Ruben 

copyright 1992 Applo Ceapuxcr, Inc. 
*ll rights reserved. 



«iLlIlL*^*"*!!2!^'"'*' "^S"* tuplraent indirect valux using the "dynaniic vaL«-. 

th. IndirKl value ue nnt to ti^iporc li.r. Ic for data "pointed to" by < fll. o.thr,»«. 
All nlu. oporatiM,. « ,h. Indira «.lu. «m then te to thrfil,. 

mll^^^'i^l'' "T*""' '^'^ *° *• Te tfc. object's 
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FOR S0XB6 MACHINES | 



/*f1nclude <types.h>V 
Include <stddef.h> 
#include <stdlfb.h> 
tffncliide <std1o.h> 
♦include «str1n9.h> 
tfinclud* <»rrno.h> 
^include <«tdarg.ti> 
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Hfnitf _CH APt_ 
#1nclutle "CMlAPI.h" 
iindif 

•Ifndef __XII(QF1LEHANDLERS 
#inclu(J» "ExamplelndFdeHa^Slers.h" 
*e«llf 

CM_CfWCTIOIiS 

^ JSr/3r^^n?J5*S5^ri:.T"'-' '"^^ « cruwCTIOHS/CM.EWJ.CfUKCTIONS Cus<d 

/* C^tlin C c!2? !^ ,!jr.rf?*'*^^r functfons. Due to seme "eoepUint*" fron. */ 



static CHHandUrAddr f IUVBlueHBt»h«KJUr(CMType tsrgetTvpe 
20 WcQn8t,CMGl«bolH»« operatlcnlype); 



/* GEHERAL MOTE. 



1?]^ ul^ ?KU i^J! "^"^ ?? P^'**^*' ^f"* handlers prwided by the 

Arr * !?• ^"1* /'"^ly*"! »«"ry adoMtion, dwiltoction, error reporter and 
8cc^ to the cef,tainer identification. These interfaces al o« « to^« tJ; XL, 



50 C/ili:^ f?::.**""'"'-'^''"' 



trwcte or cruu filt and opoi for i^datfiis (r.«linB/«ritirgJ 

both rcKis ond yriut of th.i?*,. siLr. Jii. ' "PK-'^ons *> 

tn-, .Pbtt ^ !. .?«^ >» .yp. of «« other 
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20 



aa»ic»Uy «U uo do here is oake sure the propir types «r« reoistcrcd and b^»d 

to doing . «nonn»I" CKKe-VolueO. But ft fscUt«T^ JJ^^?«m!^t?Jh1s'^ 

ptact GO u« «n .lluttrst* ho» to creatt the desfred dyniSfc^lu; 

"""^'"^ tP be used by CHUseVelueO, and the ioH^i^ 

1. The type op any of Iti bast types (H my, created CHAdSsstfTypeC » ere for 
10 Blobel mm, thet have associated netahand(er« regisiered bylSSiJurT^o! 

tn addititn lor CWitwValueC], -wetadata" end "new value" hwilleps. 

S;L'^f«C?'S^'jS ^" * description that directs 

^cMVBiueo on ncM to interpret It's "...u p»ratntters to orodise b data nnckf^r n4 

«"'!ie'^.?:S'S:r:;:t^'' »«'«»-ecTMl.Value<, pa'?^:^: 

tosL''^"th.'^S^" *"*t'»l'"tion cbto for the value" barxilers 

VSP«r IJrSi? '""J^"" ^f^""" 0" « up »nd return 

25 ^?I^uJ reSfJS. ' ^^'"^ corre.f«ndin9 to the standarS 

!::5ii?:i-u.:-fur:;f:ctiT^ «^;;:ed"t:r;y"p;.f -^-^ ^« -^"^^^^ 

''tM.'^Sj^/'""'^ T^"^ type passed to 

^" ^y^" *i?; JJ« ' '""^ ^^e -ffiep 

It is that oMcral "file" base type that most of this file Aurw^rt^ u»mi» *k * 
^thing ve do her, i. aet up th. types, register their methandLe?s/.nd dSl?; cSJeSJaLc) 

40 

CMVelue W.FUEOAKS newlndirectf iUv.lua<CHabiect object. CWropcrty prcpepty 

CHType tvp«, 

^ Cher CH^PTR •pathname, eher CM^PTR *rao<te) 

45 CHContatner container; 

CMSessfen sessiorOata; 
OfType fileType; 
CKValue dynanicValue; 
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y» !!J ISIlLf"''*!!!^' eawtion deta pointer. They are neetted for register irw */ 

Se'irrirtd'^J'T.SJS'Sa:" ^ ^ ^ 



55 eontafner a CHGttObJectContslnerCobJect); 

sessionOati a CMCetSessfontcontainer); 



*M5fJ5n'?Sn ? " ^ ~ session... 

return (HULL); ^ ...^^erc is nothing much else we can do here V 

/• Do a safety dteck on the reftReus... 
udlV^' « "W-L il property « HULL j | type HULL 1 1 pathname « «UU j | «ode - 

p^ss^trni^Tn;!^;??!.::?:! - "-^^ p^t^- - ™cde 

return (KULL>; 

> 
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n ^^^^A I' ^^^^^^ Par«;«id, you wutd check that the proptrty and type */ 

n both belonged to th« contiiner. But lets be «trustifts« for noiil ^ ♦/ 

^ ^* JSi'illiiiM"^'! type cor reregister ft just te »k« sure its registered) and V 

i« r..* 12! ?" »tB>'>»«Jl*r for thet type Mhich wHl return the •metadata" "mw V 
^» ^? {describ«l later in thU ff le). N«e" he ^??tle- V 

^* ? ".r" «t:t«h.ndler are piillfshed In the ,;iir«:t f te hJi) V 

10 ^» IIi?r JnJl^??^*^*'' *>P«» th" .Iflht «nt files es one M V 

/* ?S ^ihwi!; il'/'r S'T ' OtJseVelueO. But that requires the type ,nd V 

r »ts metahandler be rejistered just as ue do here. As a convenience ue orovlrf^ . */ 

/• «cra to do this in the he«*er file. For clearity, « do rSJ^^tti^ fe« v 
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aBetl(etiBandlert8es.ton0ete. Fit^ValueGlobelHeme, f i leC»nal■icValue#^et•handler^• 
^ IfTVpe « CWegisterType(container, FileValu.cl<±«l»U«or^ *' 
If (HleType •« (JUlL) retum (»WLL); 



20 J* IlL 1 »f?^'V*^J^"'***," * ^l'^*-'' tV^^ The caller's */ 

/* ^d? ^^^ImIT?; to be a type that describes Nhat Icini of */ 

/ file indirection this IS. The type heirarchy ne «ant looks sonetMng like this: v 

Type <botto« type) 

25 : V 

/* * y 

^ Caller's Type (top type) •/ 

C«M«aseType(typo, ftUType}; 

(! *!??^ ««««nt*aUy values for a special "base type- prooertv acUed to th. •/ 

35 /• type object. Abcnre i«'re definina ffleT^pe « a .i^sirLsr^J^^Jfor^ X 

JS^^tajr^Se^i^nStrvitul' " * '""^ CH.^.i^o V 

40 liynamfcvalue « cmn*VB(uc( object, property, type, pathnam, mode); 

^ iSth^!2rl^"il!L** »e can retirn it to the caller. Mote that the */ 

Z ^ J^i. ^ Wlle-ValueC). It has no idea uhat these arel But V 

^* ^^StiS^i^i" ''"'.'"^h *^«"- Specifically, it p«s.s th«n to tS -^?Lta^ v 
/ "^M value" handlers cXjnns the creation of the dmanic value OtteyVali^ri t^l •/ 
r there ere t« additicnal par««ters because of t^TlS Li dS^^ ht^SeV 
^ Jill:, rl"" TJ' ^'"^f =«-~*''*"S l^l'O -printft)-, although acrosTtyrdJfJe^S?*/ 
C ? S"!: telU CMHe-ValueO to consuw the additional parameters 3 */ 

/* Ilk. the "prmtfO" fortnat string tells "print* ()". "^'""^^ parameters just */ 

/» Cettinj back to the dynamic value to reiterate, the rules for dyn«ic valu» */ 
creation ar. that «h.n a OWeWValueC) or CMJseVat^O art Sl,e f fS^ LSiTtvD. V 

55 !r:si:;ic';;i^;r??::iL!'" c™ewBi«ec,, a .^tadata- ar. ««« ^^j'i::^,.r^ 

rei«-n (d^nawicValue); 
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' * "* — — • 

mctahandUr registered for the type gUbal nan*, hw • vatu6» S5ie? 2d 
criteria wi Khether a dynaaiic value fs to be created. <setir«d. That is the 



The -.metadata", "neii value-, and «use valu,« h«xller» have the follcwlng prototypce: V 
static CKMetaData oetaOats Handler(CMType type)- 

static OtBwleon fTe«Value^Handler<CKValue dyn»icB«s»VetiM, Onvpe tvoe 

. . CHBatePaclcet dataPacket); 

atottc CHBoQlean uscValue.Bandlerfawalue dynaBic88«ftValu./«Type type, 

CHHetaHandlar ^oetatiandler, CJ(»efCen'*r«#Con)f 
20 v^' Par«»Bfrs are defined later In this tile In the doc«entation for tbe.a routines. 

25 CM Type ignored » target! ype; 

<5trcirpC(char •)operBtionT>pe, CHOef inaMetaOetaOp7ype)=»0) /* -aetBdata" */ 
return «CMHandlerAddr)mctaItata_H«ndler>; ' oetadata" ♦/ 

else If tfitrcmpCtchar ♦)operationType, CKH«ValueOi)Typ«) « ov* "iwu v;iIimJi 
3D '■«um ((CKHandlerAddDneWVatue Handler)- ^ new value" */ 

* ^f^Ilf^^iif****" *>«P«''«'t*«nType, CHU«\telueOpType) =- 0)/* "use value- •/ 

return «D(HandlepAddr)useValue Handler)- f 
else - ' 

return (KULL): /* what '5 the quest (on? ♦/ 

35 ) 

40 l.^^^^frHf^lfT.I/fyyr" (wtadata for th« indir«t'f iie't^"j 

*/ 

static CNMetaData wtaOata.HwidlerCCHType type) 
CKType tnused = type; 



^ return «CHKetaOato)-)£p<-peth) Xp(=iaode)"); 



/* 

i."!l!l'!l;?7l'!??!!!'.:.!''"» praanent data for'^Je'-il^ewIi^^'^;;^;;; 



i 

. 

The "ne« value- handler is called fron ««ewValua() for dynanrtc value creation Just pri. 
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to calling tHe -use value" handler. It f> net used b,. OWseVilueO. 

"««» value" handlers are used to define InftleUietion dice for the "use valu." k^\. 

' £~ S-HS'£f ^^^^^^ 

1 n 15?*? P^ccssed fn a depth- ffrsc cwnner, so DOteuValuofi « » M.-««»t^« 

15 T4 T5 



20 



30 



Tl 



/* 

It is 



The depth- first search, start ins at 71, yiatds ttie sequence: T2 T4 T5 13 Tl Th«n *Ki 

te p... ^ the v.l« epereti-, .e^fe^ "^r^lriU" Sj:* ir.n.7K«r ""-^ 

•hert p.thn.M.en9th; /. «fM ef ,h. pe«,„..« (ine,udi„ „uii, 

tw»def .truct flieoet. FileO...; ' P»tl>n« folios the .!,e ./ 

40 (define FItcDateSIze <sfzcof(Fi(eDaia)) 

.xltipl. reai, by thrJISe «l~ hl^I^ ^'O"'" 
return „r a failure. 0 .heuld be r..v-™d T, IZ ^ili, *" """" ""^ " 

60 

SJ^LSr'"" <v™.tc...v.i„., cHTrpe type, a..t.r.d<.t 

SSI^I ^f"*««»t» ' CKCetSMsionCcontolner); 

char •pathiWB., *ino<*^, *mode, *m, c- 

FiteOsta fileData; ' * 
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10 



60 



7* 21*^!^ 'L".^" P-^w and t«ode back into variables. Ths *P| •/ 

t- S^rii " *^ CW(.uv*lu.< d 3 using */ 

n Su?2ker5?S2 tiJi^J'"" '°*'m *° extract on cf ' V 

/ MtoKacket fields back to vapfables (sort ai I f tea a "tcanfO"). */ 

i - C»ec«*ataP«ckei(typ«, wtat)ata_lUndl«f<tvp«), dataPacket, ftpsthniDe. fioode); 
conta^i^f^Sjk'*^ A" P*tK„a« par««ter In 

PCtlipn /Ol. " 



return <0); 
> 



15 /* set th> pathfiaao length in the data buffer (include the null)... 

■fileOata.pathnaiDcLength = (short) (strl«ntpath!vare) + 1); 

20 n ^tif?I?«**" open o-ds end put It In the data buff.r. Ue only accept <.mW t+)« and V 

\f )\ \^'t tHerJ!*"^ ^'"'^ « insert »i» cnX. V 



« = fileoata node- ,7t^SZ J*"" P^'^'''^ "•'"'"^ V 

25 c = *modeI+; directly in data buffer */ 

if (« «- II c w 'r'> < /« npii ^ 

C " *lD0dC4+; 

30 ''.^r:':.]' '"'^ V 

C c *B«0d»*'*; 

- _ c = *roode++; 

> 'Is* If (*fUeOata.irode == 'y') /♦ 

40 V 



> else ( 



tf C*fflcOaca.mode = 'u') /• „.,|^ 



45 , 

> else 



/* error 



return (0); ' 
55 •m » '\0'; /•null at and of the node string 



65 } """"^ aU there ia to do herel 
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/; 

i.i^?!?!*?!!!??!*'" * '^""** * ^*'"» ""^ associated metahsndUr I 
...... — .* 

The "use value* hsndler Is called tor both OtNcuValuoO and CMUaaValueO For 
□W.wv»lue(), it U «Ued after the -r«« value- hand er. EtTher^r the vaiu-. 

to mturn a po.nter to the mewhandler that will yield th. adtiiZs:^^ of tJ«i J^/ri^^s. 
?i!?*-illi^:,.r'*..'T'f^ ^^^^ ""tten to a c^uofc valuer bas, value bv 

JatSTJfJ? ""^"^ »^ th. dyn^ic value ei^J^ 

•WM vaiueN handler It not called <bs is the case for OWseVatueO). 

t JIIIILI'" r*^"*" h-ndUr, the type is passed as a convenience, it nay or r»y not 

tJL l^ J Uck into variables. Here. It nay rwt be n»«dtd. It t* po»eibte fSr a 
type object to contain or«ER data tor other properties. Types after all irl iMlil^ 

i * ^ "''^ " additional (static? J inforaatfon to the "nlu 

value- or -Hise value" handlers uhfch uoutd read the dat^ values" " 

i!!-'!!?J''f****' to the b.5c value ts as defined bv 

25 J^thSil:!'*' ''''"^ foJ!"^^ 

The refcon we build from this data has the follduing layout; ./ 

FIIE »f • ' ' P**^ the current container session */ 

char n*tf„v^Mi ^* f He variable to pointed to fiu •/ 

>; pathnanetU; /. tht START of the pathname v 

typedcf struct FileiefCon Fil««ofCon. *FilcRefConPtr; 

cSnvS;?!^?! Vr.'llT. P^^7*«^ « netd to allocate the refCon is kept just .» , 

The rafcon is atccssoble to alt the handler routines via a CMGetValueRefConO call 

^should happen to return for a failure, 0 should b. returned as the functiorresult 

static (WBooleao uscVal«e_H>ndlerCWValue dynamfcBaseValue. WTyp. type, 

^ OMetaHsndler *fietahandUr, WlefCon "refCon) 

OJContainer container - CHGetObjectCootainer(type); 

c -f!J sessioTData = OtGetSession^container); 

FileRefConPtr DiyRtfCon; 
=>o FilfOata fileOeta; 



35 



40 



eo 



^ If <CHRe«JValu*ata(dyna«icBaseV,lue, CO«>tr3lfii.0ata, 0, fildJataSfre) .= Ff leOataStze) 



return (0); 

65 > 
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myRefCon* (Flleil«fConPtr)Clftailoc(siiMfCFil«Ji«fCor) * fUtfita.pothnanieLef^h. 
sessforOata); 

it CmyRefCon WJILJ < 

5 CMError(swn*or0at8, -Cannot altocate space for file handler refCon In containar 

V"*0\"", CiaietumCenta1nerNane(canteiner}]; 
rctum (0); 

> 

10 iiMlefCon->9ess1ofCat0 « sessiorOeta; /♦ save the current session ptr •/ 

/* Read the pathname directly Into our allocated refHun... */ 

ff.tCMReadValue0ata(dyn»nilc83S»Valu», (CHPtr)inyRefCon->pathna»a. FileOataSfze. 
lb CCMSizOftlflOate.pethnamcLcngth) I- (CHSixe>f UeOata.pathnamelensth) < 

CMErrcr(sessiorOata, -Incorrect byte teneth read litila reading pathname in container 
\"*0\"", CMRet«mCcnteinerNaine(cantainer)); 
CMFree( refCon, sessiorData); 
return (Q>; 

20 3 

/• the file. We use the open mode provided in the ff leOata. If its is «wb" or V 
/* "Mbfr" then it cm only be trcn newlndireetFileValueO. This is because after we do •/ 
/♦the open, ye CHANGE the open mode in the data to "rb^' for tucure updating. This V 
^3 /• is not 8 eotisfyina solution. But there is no clean uay to teU a OWseValuaO. */ 

/* which is all future uses of the value that hIU get to us here, there's no clean */ 
/* wy to pass a different open mode. Ue could clutter up thia exanple and provide a •/ 
/* •usotndirectFileValueO" that did the "MUseValueO for the caller and chanQcd the */ 
in C '° W'-iate node (a parameter to the uselndirectri leValue) eEFORE doing a •/ 

JU /* OWseValueO. That would fake out this routine. 8ut even that would only work for */ 

/* a container opened for update node because we're rewriting the data we're using */ 
/* here, still another solution would be to pass the mode is a static sloball But »/ 
/• we have been avoidins then like the plesue everywhere. The bottoai line -• scren Itl-/ 

35 Bv«efCoo->f « fopen(niy«efCon-»pathnarae, f ileBato.node); /• open the file... */ 

if (ntyKefCon->f == MULL) i /» oops! */ 

CHError<se3slort>ata, "Cannot open \«-0\» using node \""1Y' for container V^ZX^Xn *3'' 
By«efCon->pathnon)e, f ileOata,mode, CHReturnContoinerHameCconteiner). 
strerror(ermo)); 
40 CMFreeCrefCon, sossiorOata); 

return (0); 

> 

45 strcpyCfi eOata.nwde, »>rb*'>>; /* future opens will be updating */ 

0«riteV«loeD8tB(dynaniicBaseV8lue, (CM?tr3ifile£)ata, 0, FiltfataSite); 
^ /* it's forever c^ianged) */ 

cr\ ^•'^ ^° ***'^ *» •'«*Con a"^ the pointer to the value V 

OU /♦ operations wtahandlcr to the Container Manager who called us... */ 

^netahandler = (ClWetaHand»er)fiUValu«MeiahandUr; /• return netahandUr ♦/ 
•refCon » (C»tefCon)nyttefCan; /• ...and refCon ♦/ 

etum (1); /• „,re now ready to go */ 



55 



60 



65 



/• ♦ 

I fileValutltetahandler - metehandler for a dynamic vetue operations handlers | 
... ...... ... — — ... * 

This is the metahandler that the "use value" hardier returns to the Container Hanager. 
It defines the addresses for all the value operations hawILers supported for files. 

The dynsDiic value operations handlers have the foUouirw prototypest 

static wsize fletValueSi2e_Handler(CMValue value); 
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40 



45 



niiJJzor^*" readValueOata.HandUrCCMValue value. CWtr buffer, c»*c«mt offset, OGize 
^static Crold «riteV«l«i)atB_Ha«Jler(ttVatue value. CH?tr buff.r. WCount offset, asi» 
^8t.tic void inscrtV2lu«ata.H«xJltr<CHValue value, OtPtr buffer, CMComt off.rt, CHSlze 



static void (teleteValu«Oat»_HandlerCCilValu« valu«, cuceunt offset CMSize sf«>- 
«.ric v.(d 8«Valu«lnto_H«dl.r(C«Value value. ci;comafr>er ^i^i .«bj«t 

iM C»(Pro(»rty •property, CMTyp, *type, 

. . WGeoeration •Befle^atiDn); 

stat^c void setValu»Tvp«_Handl€rCCMVolue value, CHType type)- 
static void sBtVilueGefM-ratiorcHandlerCOIValue v.luercMC«i.;ation generationl- 
static void r.lBa8eValoeJandler£CWalue value); 9"wr«tion), 

15 /. 

f^tinir '5!! "r^if^ '^•'^''^ convention, .3 ttie stantord API 

routines. Th«e handlers nust also have the sam senmtlcjt. What hai»«ns ilTS^Tt Iwlrv 
time a ^«ic value is p.».d to the Container Hwiaser. U ia vaiSSHnd tJeJ cJ«2d 

30 !V^*J **L''**^ ""t* t« b«« "real" value type 

;r tli%?r: '^Z*' «»-I:«H>*«Fil.V.lue(). TH. dyn»tc value r.tCr^cd ??a^ thl^'ya* 

t«k(na Ktantut of thit you don't liive to aioilr a haidltr unless It i» >ib.«i..r.i,. 

aavantw of the nethod <'or. excuse ine. value rat 1 00) irtieritanee hi>ri. Th- 

operations for the -setValueimo". "setValueTyp?! Jnd^atSrClS^,;?;;" ale nl 
def.n«i (i.e., „, return NULL for their addreii) « hangers! 

Note that ue actually declare all the value operations handlers as "static" sine. th.v 

loop. Ihl. IS detoctM by tt.. Conufwr M»o,.r .. „ ItjiJnJT 

Jn our Indirect file case, tht handlers «Ul uu tho refCon to do their resneniv. 

55 5r:;^:.TaJ5t.;'i;i, ?r:s;;d'sn,[ii' - if. -fs^'j? th. 

b^^lJi'^J.tC'^l^'t^^^ "Ited, all validation checks have 

routines do for nonaal values before discovering it should call a dyrJH vatu^ hitler. 
!;u;J^^S''ir"^r* '"u'*"' '"^^^ 0' fhis file, u. do not support date 
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?!Se*2^'o;Ji"L\«lS*^ ''*"^Lers operate di«ctly on » f Ue, a file 

!!ELf be used as o bottonr-nost layer of a M of layered dynamic valun For 

^iSi ««rrptian typo can havt a f ile typ. at its bearvaluT^it S« » e t?w 
5 i^vTi: ?f"'S;^ «<«it!onal b«. types of Ms o«n. So yco coutdh't. for^'^ 

o exasple, have a file type that has an encryption (us«. , 

. iSu'JSrj'hSir" J,f*"««"\dafimtIon of «flt«» types. I.e., what their handlers do 
?™^i^lS;rd«n Sn^lT;"**'* ficryptfon tese type. DnW the fact that "fiU" * 
10 v"^ * "P'^ti-^ 'n of their base value is prohlbftfrg this. 

JjSltiwljS}^*'**' ^HeValueMctahardlerfCHType tarpetTipe, CTcDnst.C«Glob«il««« 

15 static char •op-rat (onTypesD • CMGetValueSiieOpType, /• O •/ /• Operation Typ.. *j 

OWeadl/elueOataOpType, /• 1 */ 

CMJritevalueOataopType. /• 2 */ 
CMlnsertValueDataOpType, /* 3 •/ 

on CWeleteValueOateOplype, /• 4 •/ 

CHCetValoetnfoOpType, /* 5 V 

CMSetValueTypeOpType, f* & *J 
CMSetValueGenOpType, /* 7 •/ 

CKReleaseValueOpType, /* 8 V 

OCT . NULL}; 

25 char **t; 

OfType ignored ■ tarsetType; 

/♦ Look up the operation type in the operatlonTypes table ebove... */ 
30 t - eperationTypes - 1; 

while (*■H^t) if (BtrCTptiehar *)operotionType, •(> " 0) break; 

/* MOM that ue set it (hopefully), return the appropriate routine «are«... */ 
35 switch Ct - eperationTypes) t 

case 0: return ((CWIondUrAddr)getValiicSiie Hendler): f* CMGetValueSIzeCtoTvne */ 
ewe .- return «CMHandlerAddr)re«flfatueDat5 Haniler ; / cS.advJuSaJSJS V 
c«e 2: return (CC»WandlerAddr)KriteValueOate Handler ; /-iKJftJv^luijSJSjD. *, 

!:!!"!" <<f?«?fidlerA(Ur)delet«value0ata.H8ndler);/- CtealetrtfalueDatlopTySv 
rited handler or API •//• CMCetValuelnfoOprvpe •/ 



40 case 4: 



case 5: return (NULL);/* use inherited 
case 

case 7: 



« . «- <»'ULO;/* use inherited handler or API CMSrtVa wcSStST V 

case a: rerun, ((CMHandl«rAddr,releas*Valiie,Hendler); /• wSlJLlSalSX^ 4 
default: return (MULL); 

> 

50 



Attorney Docket No.: APPL: P-H20 MCP/VfStf 
wBv/appl/1120.001 170 



12/19/2003, EAST Version: 1.4,1 



133 



5,652,879 



134 



10 



171 - 

ust do iii 

/* operated i4»n by tht hsndlera 

/* 

i.?!!-!!!?!!!"?!!'!^!'"' * "'^'tvaluesiwo dyna«ic value handler 



/* 



V 

15 static OBize 9etValuoSiz«,Haodler(CMValoe value) 

FUe«tfCorf»tr r.fcon - <FUeRefconPtr)CtlGetvalwRercon(value); 
20 fsertcrefCon->f, OL, S£E._EHD,; „ ^ ^^^^ 

err = f errorCrefCon->f l; ^ 

if (err != 0) C */ 
r.tirn'JST''*'*'"^' '^'*"'"^^'~^««*tO!6etValuKQntainer<v.tue)), «trerror(err»; 



*/ 



3 



30 ^ return ««sitOfteU(refC.n->f ),; „^ 

/♦ 

. 

45 V 

«"s'!zer*'' ^''^'^"*"--»»«Jl-«a»VeUe vetuc, CKPtr hrffer, CMCCHint offset, ttSfze 

JiJTj;^*^' J-!?" ' ("leRefCort'tDCHfi.tValueRefCoivtveli/e); 

anountRsad; 
'nt err; 

if (offset >3 fiUSize) return (0); 

/* i!!T^^!;:r1*M:M i*"* 11^^- *^*^*5ize - off«t byte* ar. read V 

/ wnichever i% smaller. Th« actual eoount read returned. ' 

fSe«k(refCon->f, <long)offstt, SEEK SET); 

65 trt^^'f^src''""*''' " ^ V 
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«trerror<err»J'^'*'***^' 0«"'^nConwiner*)afw(CIIG«ValueContafo«rtvalue)), 
PMum (0); 

5 ' 

■nountReed • (CHSIze)f read ({char *)buff*r 1 

Jcrtft^ofSr''**" ^" -'oHMt) 7 maxSi« : <ffl,si« - <.ff«t)>, 

10 ^ return (araountRcad); 



15 



20 



/• 

««ic void «n-tcV«lueO»t«.H^ter(CKValue value. CHPtr buffer. c«co*t off.t, CKSize 
25 < 

»rrt err; ' 

^'Jf*'?lu' tc Mrit. beyond th. current • 

*/ 

If (Offset > fUeSire) c 

35 ^„.,«S^''''^<««on.>s«8iorOat», «Att«pt to write beybryi .of in ffl. for container 

return- "«e*«rilContaiMrN«iio(CKGetVal«eConta(ner(vatoe)) ); 

> 

40 /* «o« all tie have to da is siiply writ. tt.. d»ta tc the file... 

if (size > 0) C ^ ^ 

f«»k<refCen-»f, (lon9)of fset. SEtr SET)- **** *° *^ 

45 jrc^I'f^^Srr'""*''' ' ' /*chec. for error... 

c«,t.iS^^'ri:{;^(r"""'°*'*'' ^'^^"^ «^ N-0\" for 

strerrorterDir*'"*'***"**™"*' "*'**'"^'""'«''W««<"GetVatijeContoin«rtvalut», 
50 return; 
> 

fwrtteC(char -Jfauffer, t. («Ue_t)»ize, refCon->f); 

55 >^ 

/* 
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static vpid ins.rtValu*ata.H,r«*ler<D,Vali,e vlu., «Ptr buffer, CKCunt offset, CHSfic 
C 

FileR.fConPtr rofCon « CFi le»efCorPtr>CMDetValueRefCQnCv»lue). 
CHCotnt unusBdT « offset; "-wiivaiuBj, 

CUSfze unusedZ ■ size; 

OPtr i*ius«0 • buffer; 

CMerror(refCon->sessIarOata, ■'Insertfons into » #it. tM-nv. ^ 
si^jported", insertions Into g ffle \* Q\» for cofitsiner \"^l\n are not 

^ refCon-^pathnaiee, MR etumContainerHame<o»GetVatueC(j>tainer( value))); 



..... ' - * ' — *• 

•tatle WM «el«rtaH«.t..ito«».r(c»/.iu, v.l«, o<c,«,t off.n. «sli. 

CHSiie unusocB • size; 

^ rcfCon->pathnaine, ORctumContainerHaiwcCHGetVa tueContainer< value) »; 



/• 

We alueys nant the info for Wib dynanfe value's bae. v*i.«. rkt. 
*/ 

«at(c vo^d B.tValueInfo.H.rKller(C^al«e value, (^Container .cont-Jner. CH«,Ject -c^^iect 
CWroperty Voperty, CMType *type ' oujeci, 
^ CXGeneracfon ^generation) 



The type ro from the type ..t for the specified value. 
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c«™„u in sctV«l„eInYc.H«ndler(, obove for th. r«san th^, cede i, not used. 

static vow setVefTVp,,H.ndler(CKValue «,tue, CHType type) 
^ CliSetValueTyp,ccKGotBaseValue(valuo), type); 



...... .... 

.«.tic void MlM«v.(ue.(iMKll.r<eKV.Iu. v.(ut) 

fclos«(r»fCon.»f); , 
CH.ENDJCFUKCTIONS 
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We daim: 

1. A computer systenu comprising: 

storage means for storing a software object and an indi- 
cation of whether the software object is registered as a 
real value or a dynamic value, the storage means also 
for storing a data access handler and for storing a chain 
of dynamic value handlers if the software object is the 
dynamic value wherein each dynamic value handler 
calls a subsequent dynamic value handler in the diain 
and wherein a bottom dynamic value handler in the 
chain calls the data access handler; 

processor that determines whether the software object is 
registered as a real value or a dynamic value, iht 
processor executing the chain of dynamic value han- 
dlers if the software object is registered as the dynamic 
value such diat the data access handler returns one or 
more data values from the software object to the chain 
of dynamic value handlers and each dynamic value 
hancQer in the chain performs a data conversion opera- 
tion on the data values, the processor executing only the 
data access handler to obtain the data values from the 
software object if the software object is registered as 
the real value. 

2. The con^uter system of claim 1, wherein the processor 
assembles the chain of dynamic value handlers for the 
software object into the storage means in response to a 
request for access to the software object. 

3. The computer system of claim 2, wherein the chain of 
dynamic value handlers is specified by a hierardiical tree 
structure that corresponds to the software object 

4. The computer system of claim 3, wherein the processor 
executes the chain of dynamic value handlers and the data 
access routine according to a calling sequence specified by 
the hierarchical tree structure. 

5. The conq>uter system of claim 4, wherein the jH^ocessor 
detenoincs the calling sequence by performing a depth-first 
post-order walk on the hierarchical tree structure. 

6. The computer system of claim 1, wherein one of the 
data conversion operations comprises a data decompression 
operation on the data values obtained from the software 
object 

7. The computer system of claim 1, wherein one of the 
data conversion operations comprises a format conversion 
operation on the data values obtained from the software 
object 

8. The computer system of claim 1, wherein the storage 
means comprises a disk and the data access handler com- 
prises a read file routine for accessing a file system on the 
disk. 

9. The con^uter system of claim 1, wherein the storage 
means comprises a memory and the data access handler 
causes the processor to perform a read operation to the 
memory. 

10. The computer system of claim 1, wherein the storage 
means comprises a persistent storage means and the data 
access handler causes the processor to perfonn an input/ 
output to the persistent storage means. 

11. A method for accessing a software object, con^rising 
the steps of: 

registering the software object as a dynamic value if a data 
access operation and a chain of one or more data 
conversion operations are required to access the soft- 
ware object; 

registering the software object as a real value if only the 
data access operation is required to access the software 
object; 

determining whether the software object is registered as a 
real value or a dynamic value in response to a request 
to access the software object; 
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if the software object is registered as the dynamic value, 
then performing the data access operation on the soft- 
ware object to obtain one or more data values from tiie 
software object and then performing each data conver- 
5 sion operation in the diain on the data values; 

if the software object is registered as the real value, then 
performing the data access operation on the software 
object to obtain the data values from the software 
object. 

^0 12. The method of claim 11, wherein each data conversion 
operation in the chain is peifoimed by a cocresponding 
dynamic value handler of a chain of dynamic value handlers 
for the software object 

13. The method of claim 12, wherein the step of regis- 
tering the software object as a dynamic value includes the 
step of defining a hierarchical tree structure cocresponding to 
the software object such that the hierarchical tree structure 
specifies the chain of dynamic value handlers. 

14. The method of daim 13, wherein the step of perform^ 
20 ing each data conversion operation in the diain includes the 

step of determining a calling sequence for the chain of 
dynamic value handlers wherein the calling sequence is 
specified by the hierarchical tree structure. 

15. The method of claim 14, wherein the step of dctcr- 
25 mining the calling sequence for the chain of dynamic value 

handlers includes the step of performing a depth-first post- 
order walk on the hierarchical tree structure. 

16. The method of daim 11, wherein the data conversion 
operations include a data decompression operation on the 

30 data values from the software object 

17. The method of dahn 11, wherein the data conversion 
opaations indude a format conversion operation on the data 
values from the software object, 

18. The method of daim 11, wherein the data access 
35 operation comprises a file system access operation. 

19. The method of claim 11, wherdn the data access 
operation conqiises a memory read operation. 

20. The method of claim 11, wherein the data access 
operation comjnses an input/ou^ut operation. 

^ 21. An apparatus for accessing a software object, com- 
prising: 

means for registering the software object as a dynamic 
value if a data access operation and a chain of one or 
more data conversion operations are required to access 
the software object; 

means for registering the software object as a real value 
if only the data access operation is required to access 
the software object; 

means for determining whether the software object is 
registered as a real value or a dynamic value in 
response to a request to access the software object; 

means fcr perf(Hming the data access operation on the 
software object to obtain one or more data values from 
55 the software object and then performing each data 
conversion operation in the chain on the data values if 
the software object is registered as the dynamic value; 

means for performing the data access operation on the 
software object to obtain the data values from the 
60 software object if the software object is registered as 
the real value. 

22. The apparatus of claim 21, wherein eadi data con- 
version operation in the chain is performed by a correspond- 
ing dynamic value handler of a diain of dynamic value 

65 handlers for the software object 

23. The ^aratus of claim 22, wherein the means for 
registering the software object as a dynamic value includes 
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means for defimng a hiexarcfaical tree structure ccarespond- 
ing to the software object such that die hierarchical tree 
structure specifies the chain of dynamic value handlers. 

24. The apparatus of claim wherein the means for 
performing each data conversion operation in the chain 
includes means for detcnnining a calling sequence for the 
chain of dynamic value handles wherein the calling 
sequence is specified by the hierarchical tree structure. 

25. The apparatus of claim 24, wherein the means for 
determining the calling sequence for the chain of dynamic 
value handlers includes means for performing a depth-first 
pos^order walk on the hierarchical tree structure. 

26. The apparatus of claim 21, wherein the means for 
performing each data conversion operation includes means 
for performing a data decompression operation on the data 15 
values from the software object. 



27. The ^aratus of claim 21, wherein the means for 
performing each data conversion operation includes means 
for performing a format conversion operation on the data 
values from the software object 
^ 28. The q)paratus of daim 21, wherein the means for 
performing the data access operation con^xises means for 
performing a fUe system access operatiotL 

29. The apparatus of daim 21, wherein the means for 
IQ performing the data access operation comprises means for 

performing a memory read operation. 

30. The apparatus of daim 21, wherein the means for 
pcrfonning the data access operation conqmses means for 
performing an ii^ut/ou^ut operation. 
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